Process overview to expose content for localization

This document describes the tools and processes involved in converting a template in English to a .lang file containing localizable content and relevant information to help with localization.

This is a brief overview of the process

  • In Bedrock, when a page is in the final coding review phase in GitHub and content is finalized, an L10n label is added to the PR, signaling that it is ready for string extraction.
  • Strings are extracted from the identified templates, generating a temporary .lang file. The new strings are manually added to an existing en-US .lang file, or a brand new file added to the l10n repository. A pull request is opened to review the en-US initial content for issues or errors.
  • Another PR is created in the Langchecker repository. Langchecker is the tool used to keep track of all localizable files in the l10n repositories, and contains a set of scripts used to manage the repository.
  • After both PRs are reviewed and approved, a script will be run locally to propagate the en-US content into files in other locales. That means both adding a new file, or adding new strings to existing files.
  • Once merged to the master branch, files will be available on repository for localization, and the merge commit will be cherry-picked to bedrock-l10n, the localization production repository. Within 20 minutes, Pontoon will display the status of the new or updated files for all locales.
  • In some cases, an email through a mailing list will be sent out to communicate the localization request. At this point, the L10n tag is also removed from Bedrock’s PR.


In order to run Langchecker locally, you need a recent version of PHP (ideally 7 and above):

  • Langchecker repository has instructions on how to install the tool. The Wiki has detailed informations on all the available scripts.
  • While Apache is not needed (you can use PHP internal web server), it’s highly recommended.
  • L10n-drivers use a VMWare virtual machine based on Ubuntu LTS. This VM includes a set of Bash aliases and symbolic links designed to simplify the workflow. You can find the script used to set up the VM here, and the list of aliases here.

Step by step details for the entire process

Extract strings from a template in Bedrock

The process is detailed in this document.

Note: you only use this generated .lang file as a reference. You still need to add comments and reorder strings before exposing them for localization.

Prepare the en-US .lang file

It is very important to have a clean, error free .lang file in en-US. Once the file is approved and content is pushed into other locales, if an error is found then, it will take much more effort to correct. If localizers have already started their work, the cleanup is even messier. At that point, it is a fix in one file versus fixes in 100+ files.

Initial review should include checking the file against the page on the testing server and checking against the template. This is to ensure that there are no hard coded strings.

Note: if there is an update to an existing page, it is advised to still generate the .lang file, and copy the new string there instead of copying it from the .html file. This is to make sure, for example, that the syntax used for variable replacements is correct, and remove eventual extra white spaces between words that are not carried over to the .lang file.

Add notes and comments to the extracted file:

Add important information at the top of the file:

Proceed to the content of the file. Add a comment to the following type of strings to provide more context:

  • Page title and description. Typically, a page title string should be translated in a short or catchy way.
  • If the string contains a link, to which URL it points to. This gives context to localizers.
  • If a string is behind a tag, make sure to add the tag bindings.
  • A new string behind a tag makes another string obsolete. Make sure to add an obsolete comment to help localizers prioritize their work, and that old and new strings are next to each other. This will also make removal of old strings easier in further updates.
  • A comment for an alternative to an expression that may not be culturally relevant, or to a pun that doesn’t translate well.
  • Check English content for capitalization, hyphenated word to make sure they are consistent with the Firefox style guide (macOS vs. MacOS, sign in to vs. sign into).

When all is done, create a PR in the repo for review. Describe what the PR is for, add references to the Bedrock’s pull requests to add context for the review.

Check for possible errors such as duplicates or unmatched strings before requesting for review. In order to do this, you will need to run Langchecker locally, and make sure that both the l10n repository and Langchecker’s are using the branches you’re working on.

Work with the scripts in Langchecker

Below are some of the common commands and purposes of using Lanchecker.

You use Langchecker for the following purposes:

The following commands are used for some common tasks:

  • lang_update is to populate new and revised content in the en-US into localized files.
  • mark_active will add an ## active ## tag at the beginning of the file after checking that the entire file is translated and no errors are detected. The associate template will be live on production.
  • add_tags tracks the completion of the tagged strings, and add the tag on top of the file when all are translated.

For more details, check here.

This document details the process to update production repo.

Pontoon and Communication

Within 20 minutes, the content change will show up on Pontoon project dashboard. L10n-driver will update project deadline (high level against all other projects) and page level deadline (if applicable) when viewing the entire page status in a given locale.

An email communication about this localization request will be sent out soon after.