How to Test Migration Recipes

To test migration recipes, use the following mach command:

./mach fluent-migration-test python/l10n/fluent_migrations/bug_1485002_newtab.py

This will analyze your migration recipe to check that the migrate function exists, and interacts correctly with the migration context. Once that passes, it clones firefox-l10n-source into $OBJDIR/python/l10n, creates a reference localization by adding your local Fluent strings to the ones in firefox-l10n-source. It then runs the migration recipe, both as dry run and 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.

In most cases, a successful execution will only output the script execution:

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:

  • If the patch includes new strings that are not being migrated, the diff output will show these as removals. This occurs because the migration recipe test contains the latest version of strings from firefox-l10n-source with only migrations applied, while the reference file contains all string changes being introduced by the patch.

  • If there are pending changes to FTL files included in the recipe that landed in the last few days, and haven’t been pushed to firefox-l10n-source yet (they’re in the update branch of firefox-l10n-source), these will 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. The example output below highlights an instance where a migration failed to migrate a change to a string reference from { unified-extensions-item-message-manage } to { unified-extensions-manage-extensions.label }.

  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 (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

ls $OBJDIR/python/l10n/bug_1485002_newtab/en-US

Caveats

Be aware of hard-coded English context in migration. Consider for example:

ctx.add_transforms(
        "browser/browser/preferences/siteDataSettings.ftl",
        "browser/browser/preferences/siteDataSettings.ftl",
        transforms_from(
"""
site-usage-persistent = { site-usage-pattern } (Persistent)
""")
)

This Transform will pass a manual comparison, since the two files are identical, but will result in (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, main and update. The main branch acts as the source of truth for all available strings exposed for localizaiton, while update acts as a string quarantine. Migrations are run at the same time that strings are exposed to localizers, that is when strings in update are merged into main.

When testing fluent recipes, the fluent-migration-test script relies on a local clone of firefox-l10n-source located in ~/.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 .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 ~/.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 main within the 2 day window) by manually pulling updates with git or by removing .git/l10n_pull_marker.