Reviewing strings in Firefox desktop

• Review landed strings
  • Review strings landing in mozilla-central
  • Review strings in update branch of firefox-l10n-source
  • Run compare-locales against a localization repository
  • Merge reviewed strings to main branch of firefox-l10n-source

Review landed strings

All versions of Firefox desktop ship by localizing a single repository containing the reference English strings, called firefox-l10n-source. It is generated from strings landing in the Firefox source code repository gecko-dev (a mirror of the Mercurial repository mozilla-central which will eventually be phased out). Automation in firefox-l10n-source extracts strings from each of the version specific branches in gecko-dev (e.g. master for Nightly, beta for Beta, release for Release, etc.).

There are two branches in firefox-l10n-source: main which contains all strings currently exposed for localization, and update which acts as a string quarantine, used as a buffer to avoid exposing poor strings to the larger audience of localizers. Strings are regularly merged from update into main after a review by the Localization Team; newly added and removed strings in main are synced with our localization tool Pontoon.

Localized strings for all channels can be found in firefox-l10n, with a single subfolder for each locale.

The review process consists of three parts:

• Review strings landing in mozilla-central.
• Review strings extracted into the update branch of firefox-l10n-source. The automation runs twice a day in the repository with any changes added to a pull request against the main repository.
• Review and merge strings in the pull request to main, and start the localization process.

Things to look out for during the review process:

• Unclear strings and missing localization comments: the best way to identify them is to translate the strings, only having the string and comment as context (not the entire file, or the bug). For example: is the word used as both a noun and a verb in English? Is the ID clear enough to give context (e.g. buttonLabel)?
• String changes without new IDs.
• Duplicated strings.
• Localization issues, like misused plural forms, unclear comments, etc.

Review strings landing in mozilla-central

You can get the list of changesets touching localized strings in the last 2 days from mozilla-central. Adjust the pushdate part if you want to see more or less days.

Note: this review includes changes landing in mozilla-central, but those changes may not have landed yet in gecko-dev, and consequently in firefox-l10n-source. Once changes have completed the landing process, those strings will also be available to review in the next step - Review strings in update branch of firefox-l10n-source.

There are some unrelated changesets, like en-US dictionary updates, but the majority of landings are relevant and need to be checked for localization issues. One exception to this are strings that are purposely not meant to be exposed to localizers, typically called "preview" strings. While these strings are often saved to files within the browser/locales-preview directory, this includes any localization file not saved in a locales/en-US path.

You need to open each changeset, and identify changed files that are relevant for localization (.properties, .dtd, .ini).

In case of issues, you have two options:

• Ask sheriffs (via bug or Matrix in #sheriffs) to back out the patch.
• Ask clarifications in the bug, and decide if it’s worth to stop exposing new strings until the issue is fixed.

Review strings in update branch of firefox-l10n-source

The next step is to check changes landing in the update branch of firefox-l10n-source. Automation creates a pull request which includes any changed or added strings. Review the diff generated by the pull request.

Here are some things to look out for:

• Check if a changeset is removing strings. This should happen only when a string landed in Nightly and was removed during the same cycle, or at the beginning of a release cycle when a group of strings becomes unused in all shipping versions.

IMPORTANT: Patches including Fluent migrations need to be kept in the update branch, and can only be merged into main following the process described in this document.

Run compare-locales against a localization repository

A good next step to check for issues is to run compare-locales against a localization repository frequently updated (Italian and French are good examples).

First of all make sure that you have both firefox-l10n-source and firefox-l10n repositories cloned locally, and your local clones are updated.

compare-locales needs to be installed on your system. You can either install a specific release, or install the latest release version via pip install compare-locales. You can check that compare-locales is running correctly by checking its version:

$ compare-locales --version
compare-locales 9.0.4

Let’s assume that:

• firefox-l10n-source is cloned in ~/firefox-l10n-source.
• firefox-l10n is cloned in ~/firefox-l10n.

To run compare-locales against the string quarantine of firefox-l10n-source and Italian, first checkout the update branch of firefox-l10n-source, then run this command:

$ compare-locales ~/firefox-l10n-source/_configs/browser.toml ~/firefox-l10n it

Because the command is quite long, it’s convenient to create a Bash aliases in ~/.bash_profile for it, e.g.

cmp_moz="compare-locales ~/firefox-l10n-source/_configs/browser.toml ~/firefox-l10n it"

Reviewing the output of compare-locales against the update branch of firefox-l10n-source: most of the time, it should only report missing strings. There will be obsolete strings only if a string was removed, which is a rare event.

For example, this is the output for a fully localized locale.

$ compare-locales ~/firefox-l10n-source/_configs/browser.toml ~/firefox-l10n it
it:
changed       11768
changed_w     69481
unchanged       899
unchanged_w    1094
keys            426
92% of entries changed

Check the results for duplicated strings and errors. For example, if a new error shows up for a missing variable, it’s likely that a string changed without a new ID and introduced new variables.

You could also run compare-locales against the gecko-dev (git) or mozilla-unified (hg) repository. However, the output is going to contain a lot of noise, since it includes all strings that are obsolete for mozilla-central, but are still needed for other branches. If you’re interested in only seeing missing strings, i.e. strings that need to be added to the l10n repository, you can grep the results by piping the output to egrep '^\s*\+'.

$ compare-locales ~/mozilla-unified/browser/locales/l10n.toml ~/l10n it | egrep '^\s*\+'

Merge reviewed strings to main branch of firefox-l10n-source

If there are no issues in the update branch of firefox-l10n-source and no pending Fluent migrations, the next step is to merge the update branch into the main repository by approving and merging the pull request in GitHub. Once merged this will expose content to Pontoon.