Guidelines for Fluent Reviewers

This document is intended as a guideline for developers and reviewers when working with FTL (Fluent) files. As such, it’s not meant to replace the existing extensive documentation about Fluent.

Herald is used to set the group fluent-reviewers as blocking reviewer for any patch modifying FTL files committed to Phabricator. The person from this group performing the review will have to manually set other reviewers as blocking, if the original developer didn’t originally do it.

Hint

In case of doubt, you should always reach out to the l10n team for clarifications.

Message Identifiers

While in Fluent it’s possible to use both lowercase and uppercase characters in message identifiers, the naming convention in Gecko is to use lowercase and hyphens (kebab-case), avoiding CamelCase and underscores. For example, allow-button should be preferred to allow_button or allowButton, unless there are technically constraints – like identifiers generated at run-time from external sources – that make this impractical.

When importing multiple FTL files, all messages share the same scope in the Fluent bundle. For that reason, it’s suggested to add scope to the message identifier itself: using cancel as an identifier increases the chances of having a conflict, save-dialog-cancel-button would make it less likely.

Message identifiers are also used as the ultimate fall back in case of run-time errors. Having a descriptive message ID would make such fall back more useful for the user.

Comments

When a message includes placeables (variables), there should always be a comment explaining the format of the variable, and what kind of content it will be replaced with. This is the format suggested for such comments:

# This string is used on a new line below the add-on name
# Variables:
#   $name (String) - Add-on author name
cfr-doorhanger-extension-author = by { $name }

By default, a comment is bound to the message immediately following it. Fluent supports both file-level and group-level comments. Be aware that a group comment will apply to all messages following that comment until the end of the file. If that shouldn’t be the case, you’ll need to “reset” the group comment, by adding an empty one (##), or moving the section of messages at the end of the file.

Comments are fundamental for localizers, since they don’t see the file as a whole, or changes as a fragment of a larger patch. Their work happens on a message at a time, and the context is only provided by comments.

License headers are standalone comments, that is, a single # as prefix, and the comment is followed by at least one empty line.

Changes to Existing Messages

You must update the message identifier if:

  • The meaning of the sentence has changed.

  • You’re changing the morphology of the message, by adding or removing attributes.

Messages are identified in the entire localization toolchain by their ID. For this reason, there’s no need to change attribute names.

If your changes are relevant only for English — for example, to correct a typographical error or to make letter case consistent — then there is generally no need to update the message identifier.

There is a grey area between needing a new ID or not. In some cases, it will be necessary to look at all the existing translations to determine if a new ID would be beneficial. You should always reach out to the l10n team in case of doubt.

Changing the message ID will invalidate the existing translation, the new message will be reported as missing in all tools, and localizers will have to retranslate it. This is the only reliable method to ensure that localizers update existing localizations, and run-time stop using obsolete translations.

You must also update all instances where that message identifier is used in the source code, including localization comments.

Non-text Elements in Messages

When a message includes non text-elements – like anchors or images – make sure that they have a data-l10n-name associated to them. Additional attributes, like the URL for an anchor or CSS classes, should not be exposed for localization in the FTL file. More details can be found in this page dedicated to DOM overlays.

This information is not relevant if your code is using fluent-react, where DOM overlays work differently.

Message References

Consider the following example:

newtab-search-box-search-the-web-text = Search the Web
newtab-search-box-search-the-web-input =
    .placeholder = { newtab-search-box-search-the-web-text }
    .title = { newtab-search-box-search-the-web-text }

This might seem to reduce the work for localizers, but it actually doesn’t help:

  • A change to the referenced message (newtab-search-box-search-the-web-text) would require a new ID also for all messages referencing it.

  • Translation memory can help with matching text, not with message references.

On the other hand, this approach is helpful if, for example, you want to reference another element of the UI in your message:

help-button = Help
help-explanation = Click the { help-button} to access support

This enforces consistency and, if help-button changes, all other messages will need to be updated anyway.

Terms

Fluent supports a specific type of message, called term. Terms are similar to regular messages but they can only be used as references in other messages. They are best used to define vocabulary and glossary items which can be used consistently across the localization of the entire product.

Terms are typically used for brand names, like Firefox or Mozilla: it allows to have them in one easily identifiable place, and raise warnings when a localization is not using them. It helps enforcing consistency and brand protection. If you simply need to reference a message from another message, you don’t need a term: cross references between messages are allowed, but they should not be abused, as already described.

Variants and plurals

Consider the following example:

items-selected =
    { $num ->
        [0] Select items.
        [one] One item selected.
       *[other] { $num } items selected.
    }

In this example, there’s no guarantee that all localizations will have this variant covered, since variants are private by design. The correct approach for the example would be to have a separate message for the 0 case:

# Separate messages which serve different purposes.
items-select = Select items
# The default variant works for all values of the selector.
items-selected =
    { $num ->
        [one] One item selected.
       *[other] { $num } items selected.
    }

As a rule of thumb:

  • Use variants only if the default variant makes sense for all possible values of the selector.

  • The code shouldn’t depend on the availability of a specific variant.

More examples about selector and variant abuses can be found in this wiki.

In general, also avoid putting a selector in the middle of a sentence, like in the example below:

items-selected =
    { $num ->
        [one] One item.
       *[other] { $num } items
    } selected.

1 should only be used in case you want to cover the literal number. If it’s a standard plural, you should use the one category for singular. Also make sure to always pass the variable to these messages as a number, not as a string.

Access Keys

The following is a simple potential example of an access key:

example-menu-item =
    .label = Menu Item
    .accesskey = M

Access keys are used in menus in order to help provide easy keyboard shortcut access. They are useful for both power users, and for users who have accessibility needs. It is helpful to first read the Access keys guide in the Windows Developer documentation, as it outlines the best practices for Windows applications.

There are some differences between operating systems. Linux mostly follows the same practices as Windows. However, macOS in general does not have good support for accesskeys, especially in menus.

When choosing an access key, it’s important that it’s unique relative to the current level of UI. It’s preferable to avoid letters with descending parts, such as g, j, p, and q as these will not be underlined nicely in Windows or Linux. Other problematic characters are ones which are narrow, such as l, i and I. The underline may not be as visible as other letters in sans-serif fonts.

Linter

mach lint includes a l10n linter, called moz-l10n-lint. It can be run locally by developers but also runs on Treeherder: in the Build Status section of the diff on Phabricator, open the Treeherder Jobs link and look for the l1nt job.

Besides displaying errors and warnings due to syntax errors, it’s particularly important because it also checks for message changes without new IDs, and conflicts with the firefox-l10n-source repository used to ship localized versions of Firefox.

Warning

Currently, there’s an issue preventing warnings to be displayed in Phabricator. Checks can be run locally using ./mach lint -l l10n -W.

Migrating Strings From Legacy or Fluent Files

If a patch is moving legacy strings (.properties, .DTD) to Fluent, it should also include a recipe to migrate existing strings to FTL messages. The same is applicable if a patch moves existing Fluent messages to a different file, or changes the morphology of existing messages without actual changes to the content.

Documentation on how to write and test migration recipes is available in this page.