commit df13c8ab3392f013644dde2aa474bc0bf1351873
parent 62e523ce64f5a2fd04523e2217667393a5faaa0b
Author: Bryan Olsson <bolsson@mozilla.com>
Date: Tue, 21 Oct 2025 17:28:18 +0000
Bug 1994504 - Add advanced instructions for testing migrations, r=flod DONTBUILD
Differential Revision: https://phabricator.services.mozilla.com/D269131
Diffstat:
2 files changed, 70 insertions(+), 8 deletions(-)
diff --git a/intl/l10n/docs/migrations/localizations.rst b/intl/l10n/docs/migrations/localizations.rst
@@ -12,10 +12,10 @@ How Migrations Are Run on l10n Repositories
===========================================
Once a patch including new FTL strings and a migration recipe lands in
-mozilla-central, the Localization Team will perform a series of actions to migrate
+`mozilla-firefox`, the Localization Team will perform a series of actions to migrate
strings for all 100+ localizations:
- - New Fluent strings land in `mozilla-central`, together with a migration
+ - New Fluent strings land in `mozilla-firefox`, together with a migration
recipe.
- New strings are added to an `update` branch of `firefox-l10n-source`_,
a unified repository including strings for all shipping versions of Firefox,
@@ -28,15 +28,15 @@ strings for all 100+ localizations:
Migration recipes could be run multiple times within a release cycle if more
patches containing migrations land after the first.
-Migration recipes are periodically removed from `mozilla-central`. This clean-up
+Migration recipes are periodically removed from `mozilla-firefox`. This clean-up
process will typically leave recipes from the most recent 2 or 3 cycles. Older
-recipes are stored in `this repository`__ .
+recipes are stored in `this repository`_ .
.. tip::
A script to run migrations on all l10n repositories is available in `this
- repository`__, automating part of the steps described for manual testing, and
+ repository`_, automating part of the steps described for manual testing, and
it could be adapted to local testing.
- __ https://github.com/flodolo/fluent-migrations
.. _firefox-l10n-source: https://github.com/mozilla-l10n/firefox-l10n-source/
+.. _this repository: https://github.com/flodolo/fluent-migrations
diff --git a/intl/l10n/docs/migrations/testing.rst b/intl/l10n/docs/migrations/testing.rst
@@ -26,7 +26,17 @@ as actual migration. Finally it analyzes the commits, and checks if any
migrations were actually run and the bug number in the commit message matches
the migration name.
-At the end of the execution, the output will include a diff if there are
+In most cases, a successful execution will only output the script execution:
+
+.. code-block:: bash
+
+ Running migration fluent_migrations.bug_1994180_fix_manage_extensions_reference for en-US
+ Writing to /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/en-US/browser/browser/unifiedExtensions.ftl
+ Committing changeset: Bug 1994180 - Change unified-extensions-item-message-manage reference to unified-extensions-manage-extensions.label, part 1
+ Writing to /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/en-US/browser/browser/unifiedExtensions.ftl
+ Committing changeset: Bug 1994180 - Change unified-extensions-item-message-manage reference to unified-extensions-manage-extensions.label, part 2
+
+In some instance, the output after execution will include a diff if there are
differences between the migrated files and the reference content (blank lines
are automatically ignored). There are cases where a diff is still expected, even
if the recipe is correct:
@@ -42,7 +52,34 @@ if the recipe is correct:
show up as additions.
If a diff is displayed and the patch doesn't fall into the highlighted cases,
-there may be an issue with the migration recipe.
+there may be an issue with the migration recipe. The example output below highlights
+an instance where a migration failed to migrate a change to a string reference from
+:bash:`{ unified-extensions-item-message-manage }` to
+:bash:`{ unified-extensions-manage-extensions.label }`.
+
+.. code-block:: bash
+
+ Running migration fluent_migrations.bug_1994180_fix_manage_extensions_reference for en-US
+ Writing to /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/en-US/browser/browser/unifiedExtensions.ftl
+ Committing changeset: Bug 1994180 - Change unified-extensions-item-message-manage reference to unified-extensions-manage-extensions.label, part 1
+ Writing to /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/en-US/browser/browser/unifiedExtensions.ftl
+ Committing changeset: Bug 1994180 - Change unified-extensions-item-message-manage reference to unified-extensions-manage-extensions.label, part 2
+ --- /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/reference/browser/browser/unifiedExtensions.ftl
+ +++ /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/en-US/browser/browser/unifiedExtensions.ftl
+ @@ -17,8 +17,8 @@
+ unified-extensions-empty-reason-extension-not-enabled = You have extensions installed, but not enabled
+ # In this headline, “Level up” means to enhance your browsing experience.
+ unified-extensions-empty-reason-zero-extensions-onboarding = Level up your browsing with extensions
+ -unified-extensions-empty-content-explain-enable2 = Select “{ unified-extensions-manage-extensions.label }” to enable them in settings.
+ -unified-extensions-empty-content-explain-manage2 = Select “{ unified-extensions-manage-extensions.label }” to manage them in settings.
+ +unified-extensions-empty-content-explain-enable2 = Select “{ unified-extensions-item-message-manage }” to enable them in settings.
+ +unified-extensions-empty-content-explain-manage2 = Select “{ unified-extensions-item-message-manage }” to manage them in settings.
+ unified-extensions-empty-content-explain-extensions-onboarding = Personalize { -brand-short-name } by changing how it looks and performs or boosting privacy and safety.
+
+This diff output indicates that the string value being generated by the migration
+(:bash:`Select “{ unified-extensions-item-message-manage }” to enable them in settings.`)
+differs from the intended string value included in the Fluent file of the patch
+(:bash: `{ unified-extensions-manage-extensions.label }`).
You can inspect the generated repository further by looking at
@@ -71,3 +108,28 @@ Be aware of hard-coded English context in migration. Consider for example:
This Transform will pass a manual comparison, since the two files are identical,
but will result in :js:`(Persistent)` being hard-coded in English for all
languages.
+
+firefox-l10n-source repository
+------------------------------
+
+`firefox-l10n-source`_ is a unified repository including strings for all
+shipping versions of Firefox, and is also used as a buffer before exposing strings
+to localizers. There are typically two branches available, :bash:`main` and
+:bash:`update`. The :bash:`main` branch acts as the source of truth for all
+available strings exposed for localizaiton, while :bash:`update` acts as a
+string quarantine. Migrations are run at the same time that strings are exposed
+to localizers, that is when strings in :bash:`update` are merged into :bash:`main`.
+
+When testing fluent recipes, the :bash:`fluent-migration-test` script relies on a
+local clone of :bash:`firefox-l10n-source` located in :bash:`~/.mozbuild/l10n-source`.
+When the mach command is run, the script either clones the remote repo if it doesn't
+exist or pulls the latest changesets if :bash:`.git/l10n_pull_marker` is older than
+2 days. Otherwise the current version is used.
+
+Some advanced testing can be done by making changes in :bash:`~/.mozbuild/l10n-source`
+such as checking out previous commits or adding strings manually. You can also force
+sync to get the latest strings (if some have merged into :bash:`main` within the
+2 day window) by manually pulling updates with git or by removing
+:bash:`.git/l10n_pull_marker`.
+
+.. _firefox-l10n-source: https://github.com/mozilla-l10n/firefox-l10n-source/
