{{ ftl('example-page-desc') }}
.. _Fluent file syntax: https://projectfluent.org/fluent/guide/ :abbr:`FTL (Fluent Translation List)` String IDs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Our convention for string ID creation is the following: 1. String IDs should be all lower-case alphanumeric characters. 2. Words should be separated with hyphens. 3. IDs should be prefixed with the name of the template file (e.g. ``firefox-new-skyline`` for ``firefox-new-skyline.html``) 4. If you need to create a new string for the same place on a page and to transition to it as it is translated, you can add a version suffix to the string ID: e.g. ``firefox-new-skyline-main-page-title-v2``. 5. The ID should be as descriptive as possible to make sense to the developer, but could be anything as long as it adheres to the rules above. Using brand names ~~~~~~~~~~~~~~~~~ Common Mozilla brand names are stored in a global `brands.ftl`_ file, in the form of `terms`_. Terms are useful for keeping brand names separated from the rest of the translations, so that they can be managed in a consistent way across all translated files, and also updated easily in a global context. In general the brand names in this file remain in English and should not be translated, however locales still have the choice and control to make adjustments should it suit their particular language. Only our own brands should be managed this way, brands from other companies should not. If you are concerned that the brand is a common word and may be translated, leave a comment for the translators. .. note:: We are trying to phase out use of ``{ -brand-name-firefox-browser }`` please use ``{ -brand-name-firefox } browser``. .. code-block:: fluent -brand-name = Firefox example-about = About { -brand-name }. example-update-successful = { -brand-name } has been updated. # "Safari" here refers to the competing web browser example-compare = How does { -brand-name } compare to Safari? .. important:: When adding a new term to ``brands.ftl``, the new term should also be manually added to the `mozilla-l10n/www-l10n`_ repo for *all locales*. The reason for this is that if a term does not exist for a particular locale, then it does not fall back to English like a regular string does. Instead, the term variable name is displayed on the page. .. _brands.ftl: https://github.com/mozilla/bedrock/blob/main/l10n/en/brands.ftl .. _terms: https://projectfluent.org/fluent/guide/terms.html .. _mozilla-l10n/www-l10n: https://github.com/mozilla-l10n/www-l10n Variables ~~~~~~~~~ Single hash comments are applied only to the string immediately following them. They should be used to provide additional context for the translators including: 1. What the values of variables are. 2. Context about where string appears on the page if it is not visible or references other elements on the page. 3. Explanations of English idioms and jargon that may be confusing to non-native speakers. .. code-block:: fluent # Variables: # $savings (string) - the percentage saved from the regular price, not including the % Examples: 50, 70 example-bundle-savings = Buy now for { $savings }% off. # Context: Used as an accessible text alternative for an image example-bookmark-manager-alt = The bookmark manager window in { -brand-name-firefox }. # Context: This lists the various websites and magazines who have mentioned Firefox Relay. # Example: "As seen in: FORBES magainze and LifeHacker" example-social-proof = As seen in: example-privacy-on-every = Want privacy on every device? # "You got it" here is a casual answer to the previous question, "Want privacy on every device?" example-you-got-it = You got it. Get { -brand-name-firefox } for mobile. HTML with attributes ******************** When passing HTML tags with attributes into strings for translation, remove as much room for error as possible by putting all the attributes and their values in a single variable. (This is most common with links and their href attributes but we do occasionally pass classes with other tags.) .. code-block:: fluent # Variables: # $attrs (attrs) - link to https://www.mozilla.org/about/ example-created = { -brand-name-firefox } was created by { -brand-name-mozilla }. # Variables: # $class (string) - CSS class used to replace brand name with wordmark logo example-firefox-relay = Add { -brand-name-firefox-relay } .. code-block:: jinja {% set created_attrs = 'href="%s" data-cta-type="link" data-cta-text="created by Mozilla"'|safe|format(url('mozorg.about.index')) %}{{ ftl('example-created', attrs=created_attrs) }}
{{ ftl('example-firefox-relay', class_name='class="mzp-c-wordmark mzp-t-wordmark-md mzp-t-product-relay"') }} Obsolete strings ~~~~~~~~~~~~~~~~ When new strings are added to a page sometimes they update or replace old strings. Obsolete strings & IDs should be removed from ftl files immediately if they are not being used as a fallback. If they are being kept as a fallback they should be removed after 2 months. When you add a comment marking a string as obsolete, add the date when it can be removed to the comment. .. code-block:: fluent # Obsolete string (expires: 2024-03-18) example-old-string = Fifty thousand year old twisted bark threads. Fallback ******** If you need to create a new string for the same place on a page and would like to keep the old one as a fallback, you can add a version suffix to the new string ID: e.g. ``firefox-new-skyline-main-page-title-v2``. .. code-block:: fluent example-block-title-v2 = Security, reliability and speed — on every device, anywhere you go. # Obsolete string (expires: 2024-03-18) example-block-title = Security, reliability and speed — from name you can trust. The ``ftl`` helper function has the ability to accept a fallback string ID and is described in the next section. Remove ****** If the new string is fundamentally different a new string ID should be created and the old one deleted. For example, if the page is going from talking about the Google Translate extension to promoting our own Firefox Translate feature the old strings are not appropriate fall backs. The old strings and IDs should be deleted: .. code-block:: fluent example-translate-title = The To Google Translate extension makes translating the page you’re on easier than ever. example-translate-content = Google Translate, with over 100 languages* at the ready, is used by millions of people around the world. The new strings should have different IDs and not be versioned: .. code-block:: fluent example-translate-integrated-title = { -brand-name-firefox } now comes with an integrated translation tool. example-translate-integrated-content = Unlike some cloud-based alternatives, { -brand-name-firefox } translates text locally, so the content you’re translating doesn’t leave your machine. The ``ftl_has_messages`` jinja helper would be useful here and is described in the next section. The ``ftl`` helper function ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``ftl()`` function takes a string ID and returns the string in the current language, or simplified english if the string isn't translated. If you'd like to use a different string ID in the case that the primary one isn't translated you can specify that like this: .. code-block:: python ftl('primary-string-id', fallback='fallback-string-id') When a fallback is specified it will be used only if the primary isn't translated in the current locale. English locales (e.g. en-US, en-GB) will never use the fallback and will print the simplified english version of the primary string if not overridden in the more specific locale. You can also pass in replacement variables into the ``ftl()`` function for use with `fluent variables`_. If you had a variable in your fluent file like this: .. code-block:: fluent welcome = Welcome, { $user }! You could use that in a template like this: .. code-block:: jinja{{ ftl('new-description') }}
{% else %}{{ ftl('description') }}
{% endif %} If you'd like to have it return true when any of the given message IDs exist in the translation instead of requiring all of them, you can pass the optional ``require_all=False`` parameter and it will do just that. There is a version of this function for use in views called ``has_messages``. It works exactly the same way but is meant to be used in the view Python code. .. code-block:: python # views.py from lib.l10n_utils import render from lib.l10n_utils.fluent import ftl, has_messages def about_view(request): ftl_files = 'mozorg/about' if has_messages('about-hello-v2', 'about-title-v2', ftl_files=ftl_files): hello_string = ftl('about-hello-v2', ftl_files=ftl_files) title_string = ftl('about-title-v2', ftl_files=ftl_files) else: hello_string = ftl('about-hello', ftl_files=ftl_files) title_string = ftl('about-title', ftl_files=ftl_files) render(request, 'about.html', {'hello': hello_string, 'title': title_string}, ftl_files=ftl_files) .. _fluent variables: https://projectfluent.org/fluent/guide/variables.html .. _specifying_fluent_files: Specifying Fluent files ----------------------- You have to tell the system which Fluent files to use for a particular template or view. This is done in either the ``page()`` helper in a ``urls.py`` file, or in the call to ``l10n_utils.render()`` in a view. Using the ``page()`` function ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you just need to render a template, which is quite common for bedrock, you will probably just add a line like the following to your ``urls.py`` file: .. code-block:: python urlpatterns = [ page('about', 'about.html'), page('about/contact', 'about/contact.html'), ] To tell this page to use the Fluent framework for l10n you just need to tell it which file(s) to use: .. code-block:: python urlpatterns = [ page('about', 'about.html', ftl_files='mozorg/about'), page('about/contact', 'about/contact.html', ftl_files=['mozorg/about/contact', 'mozorg/about']), ] The system uses the first (or only) file in the list to determine which locales are active for that URL. You can pass a string or list of strings to the ``ftl_files`` argument. The files you specify can include the ``.ftl`` extension or not, and they will be combined with the list of default files which contain strings for global elements like navigation and footer. There will also be files for reusable widgets like the newsletter form, but those should always come last in the list. Using the class-based view ~~~~~~~~~~~~~~~~~~~~~~~~~~ Bedrock includes a generic class-based view (CBV) that sets up l10n for you. If you need to do anything fancier than just render the page, then you can use this: .. code-block:: python from lib.l10n_utils import L10nTemplateView class AboutView(L10nTemplateView): template_name = 'about.html' ftl_files = 'mozorg/about' Using that CBV will do the right things for l10n, and then you can override other useful methods (e.g. ``get_context_data``) to do what you need. Also, if you do need to do anything fancy with the context, and you find that you need to dynamically set the fluent files list, you can easily do so by setting ``ftl_files`` in the context instead of the class attribute. .. code-block:: python from lib.l10n_utils import L10nTemplateView class AboutView(L10nTemplateView): template_name = 'about.html' def get_context_data(self, **kwargs): ctx = super().get_context_data(**kwargs) ftl_files = ['mozorg/about'] if request.GET.get('fancy'): ftl_files.append('fancy') ctx['ftl_files'] = ftl_files return ctx A common case is needing to use :abbr:`FTL (Fluent Translation List)` files when one template is used, but not with another. In this case you would have some logic to decide which template to use in the ``get_template_names()`` method. You can set the ``ftl_files_map`` class variable to a dict containing a map of template names to the list of FTL files for that template (or a single file name if that's all you need). .. code-block:: python # views.py from lib.l10n_utils import L10nTemplateView # class-based view example class AboutView(L10nTemplateView): ftl_files_map = { 'about_es.html': ['about_es'] 'about_new.html': ['about'] } def get_template_names(self): if self.request.locale.startswith('en'): template_name = 'about_new.html' elif self.request.locale.startswith('es'): template_name = 'about_es.html' else: # FTL system not used template_name = 'about.html' return [template_name] If you need for your URL to use multiple Fluent files to determine the full list of active locales, for example when you are redesigning a page and have multiple templates in use for a single URL depending on locale, you can use the `activation_files` parameter. This should be a list of :abbr:`FTL (Fluent Translation List)` filenames that should all be used when determining the full list of translations for the URL. Bedrock will gather the full list for each file and combine them into a single list so that the footer language switcher works properly. Another common case is that you want to keep using an old template for locales that haven't yet translated the strings for a new one. In that case you can provide an ``old_template_name`` to the class and include both that template and ``template_name`` in the ``ftl_files_map``. Once you do this the view will use the template in ``template_name`` only for requests for an active locale for the FTL files you provided in the map. .. code-block:: python from lib.l10n_utils import L10nTemplateView class AboutView(L10nTemplateView): template_name = 'about_new.html' old_template_name = "about.html" ftl_files_map = { "about_new.html": ["about_new", "about_shared"], "about.html": ["about", "about_shared"], } In this example when the ``about_new`` FTL file is active for a locale, the ``about_new.html`` template will be rendered. Otherwise the ``about.html`` template would be used. Using in a view function ~~~~~~~~~~~~~~~~~~~~~~~~ Lastly there's the good old function views. These should use ``l10n_utils.render`` directly to render the template with the context. You can use the ``ftl_files`` argument with this function as well. .. code-block:: python from lib.l10n_utils import render def about_view(request): render(request, 'about.html', {'name': 'Duder'}, ftl_files='mozorg/about') Fluent File Configuration ------------------------- In order for a Fluent file to be extracted through automation and sent out for localization, it must first be configured to go through one or more distinct pipelines. This is controlled via a set of configuration files: - `Vendor`_, locales translated by an agency, and paid for by Marketing (locales covered by staff are also included in this group). - `Pontoon`_, locales translated by Mozilla contributors. - `Special templates`_, for locales with dedicated templates that don't go through the localization process (not currently used). Each configuration file consists of a pre-defined set of locales for which each group is responsible for translating. The locales defined in each file should not be changed without first consulting the with L10n team, and such changes should not be a regular occurrence. To establish a localization strategy for a Fluent file, it needs to be included as a path in one or more configuration files. For example: .. code-block:: text [[paths]] reference = "en/mozorg/mission.ftl" l10n = "{locale}/mozorg/mission.ftl" You can read more about configuration files in the `L10n Project Configuration`_ docs. .. important:: Path definitions in Fluent configuration files are not source order dependent. A broad definition using a wild card can invalidate all previous path definitions for example. Paths should be defined carefully to avoid exposing .ftl files to unintended locales. Using a combination of vendor and pontoon configuration offers a flexible but specific set of options to choose from when it comes to defining an l10n strategy for a page. The available choices are: #. Staff locales. #. Staff + select vendor locales. #. Staff + all vendor locales. #. Staff + vendor + pontoon. #. All pontoon locales (for non-marketing content only). When choosing an option, it's important to consider that vendor locales have a cost associated with them, and pontoon leans on the goodwill of our volunteer community. Typically, only non-marketing content should go through Pontoon for all locales. Everything that is marketing related should feature one of the staff/vendor/pontoon configurations. .. _Vendor: https://github.com/mozilla/bedrock/blob/main/l10n/configs/vendor.toml .. _Pontoon: https://github.com/mozilla/bedrock/blob/main/l10n/configs/pontoon.toml .. _Special templates: https://github.com/mozilla/bedrock/blob/main/l10n/configs/special-templates.toml .. _L10n Project Configuration: https://moz-l10n-config.readthedocs.io/ Fluent File Activation ---------------------- Fluent files are activated automatically when processed from the l10n team's repo into our own based on a couple of rules. 1. If a fluent file has a group of required strings, all of those strings must be present in the translation in order for it to be activated. 2. A translation must contain a minimum percent of the string IDs from the English file to be activated. If both of these conditions are met the locale is activated for that particular Fluent file. Any view using that file as its primary (first in the list) file will be available in that locale. Deactivation ~~~~~~~~~~~~ If the automated system activates a locale but we for some reason need to ensure that this page remains unavailable in that locale, we can add this locale to a list of deactivated locales in the metadata file for that :abbr:`FTL (Fluent Translation List)` file. For example, say we needed to make sure that the `mozorg/mission.ftl` file remained inactive for German, even though the translation is already done. We would add ``de`` to the ``inactive_locales`` list in the ``metadata/mozorg/mission.json`` file: .. code-block:: json { "active_locales": [ "de", "fr", "en-GB", "en-US", ], "inactive_locales": [ "de" ], "percent_required": 85 } This would ensure that even though ``de`` appears in both lists, it will remain deactivated on the site. We could just remove it from the active list, but automation would keep attempting to add it back, so for now this is the best solution we have, and is an indication of the full list of locales that have satisfied the rules. Alternate Rules ~~~~~~~~~~~~~~~ It's also possible to change the percentage of string completion required for activation on a per-file basis. In the same metadata file as above, if a ``percent_required`` key exists in the JSON data (see above) it will be used as the minimum percent of string completion required for that file in order to activate new locales. .. note:: Once a locale is activated for a Fluent file it will **NOT** be automatically deactivated, even if the rules change. If you need to deactivate a locale you should follow the `Deactivation`_ instructions. Activation Status ~~~~~~~~~~~~~~~~~ You can determine and use the activation status of a Fluent file in a view to make some decisions; what template to render for example. The way you would do that is with the ``ftl_file_is_active`` function. For example: .. code-block:: python # views.py from lib.l10n_utils import L10nTemplateView from lib.l10n_utils.fluent import ftl_file_is_active # class-based view example class AboutView(L10nTemplateView): ftl_files_map = { 'about.html': ['about'] 'about_new.html': ['about_new', 'about'] } def get_template_names(self): if ftl_file_is_active('mozorg/about_new'): template_name = 'about_new.html' else: template_name = 'about.html' return [template_name] # function view example def about_view(request): if ftl_file_is_active('mozorg/about_new'): template = 'mozorg/about_new.html' ftl_files = ['mozorg/about_new', 'mozorg/about'] else: template = 'about.html' ftl_files = ['mozorg/about'] render(request, template, ftl_files=ftl_files) Active Locales ~~~~~~~~~~~~~~ To see which locales are active for a particular .ftl file you can either look in the metadata file for that .ftl file, which is the one with the same path but in the ``metadata`` folder instead of a locale folder in the www-l10n repository. Or if you'd like something a bit nicer looking and more convenient there is the ``active_locales`` management command: .. code-block:: bash $ ./manage.py l10n_update .. code-block:: bash $ ./manage.py active_locales mozorg/mission .. code-block:: bash There are 91 active locales for mozorg/mission.ftl: - af - an - ar - ast - az - be - bg - bn ... You get an alphabetically sorted list of all of the active locales for that .ftl file. You should run ``./manage.py l10n_update`` as shown above for the most accurate and up-to-date results. String extraction ----------------- The string extraction process for both new .ftl content and updates to existing .ftl content is handled through automation. On each commit to ``main`` a command is run that looks for changes to the ``l10n/`` and ``l10n-pocket/`` directories. If a change is detected, it will copy those files into a new branch in `mozilla-l10n/www-l10n`_ and then a bot will open a pull request containing those changes. Once the pull request has been reviewed and merged by the L10n team, everything is done. To view the state of the latest automated attempt to open an L10N PR, see: * `Mozorg L10N PR action`_ * `Pocket L10N PR action`_ (We also just try to open L10N PRs every 3 hours, to catch any failed jobs that are triggered by a commit to ``main``) .. _mozilla-l10n/www-l10n: https://github.com/mozilla-l10n/www-l10n .. _Mozorg L10N PR action: https://github.com/mozilla/bedrock/actions/workflows/send_mozorg_fluent_strings_to_l10n_org.yml .. _Pocket L10N PR action: https://github.com/mozilla/bedrock/actions/workflows/send_pocket_fluent_strings_to_l10n_org.yml CSS --- If a localized page needs some locale-specific style tweaks, you can add the style rules to the page's stylesheet like this: .. code-block:: css html[lang="it"] #features li { font-size: 20px; } html[dir="rtl"] #features { float: right; } If a locale needs site-wide style tweaks, font settings in particular, you can add the rules to ``/media/css/l10n/{{LANG}}/intl.css``. Pages on Bedrock automatically includes the CSS in the base templates with the `l10n_css` helper function. The CSS may also be loaded directly from other Mozilla sites with such a URL: ``//mozorg.cdn.mozilla.net/media/css/l10n/{{LANG}}/intl.css``. *Open Sans*, the default font on mozilla.org, doesn't offer non-Latin glyphs. ``intl.css`` can have ``@font-face`` rules to define locale-specific fonts using custom font families as below: * *X-LocaleSpecific-Light*: Used in combination with *Open Sans Light*. The font can come in 2 weights: normal and optionally bold * *X-LocaleSpecific*: Used in combination with *Open Sans Regular*. The font can come in 2 weights: normal and optionally bold * *X-LocaleSpecific-Extrabold*: Used in combination with *Open Sans Extrabold*. The font weight is 800 only Here's an example of ``intl.css``: .. code-block:: css @font-face { font-family: X-LocaleSpecific-Light; font-weight: normal; font-display: swap; src: local(mplus-2p-light), local(Meiryo); } @font-face { font-family: X-LocaleSpecific-Light; font-weight: bold; font-display: swap; src: local(mplus-2p-medium), local(Meiryo-Bold); } @font-face { font-family: X-LocaleSpecific; font-weight: normal; font-display: swap; src: local(mplus-2p-regular), local(Meiryo); } @font-face { font-family: X-LocaleSpecific; font-weight: bold; font-display: swap; src: local(mplus-2p-bold), local(Meiryo-Bold); } @font-face { font-family: X-LocaleSpecific-Extrabold; font-weight: 800; font-display: swap; src: local(mplus-2p-black), local(Meiryo-Bold); } Localizers can specify locale-specific fonts in one of the following ways: * Choose best-looking fonts widely used on major platforms, and specify those with the ``src: local(name)`` syntax * Find a best-looking free Web font, add the font files to ``/media/fonts/``, and specify those with the ``src: url(path)`` syntax * Create a custom Web font to complement missing glyphs in *Open Sans*, add the font files to ``/media/fonts/l10n/``, and specify those with the ``src: url(path)`` syntax. `M+ 2c