1 files changed, 190 insertions, 0 deletions
diff --git a/comm/docs/l10n/fluent_migrations.md b/comm/docs/l10n/fluent_migrations.md
new file mode 100644
index 0000000000..13639ca187
--- /dev/null
+++ b/comm/docs/l10n/fluent_migrations.md
@@ -0,0 +1,190 @@
+# Migrating Strings to Fluent Files
+
+Like [Firefox](https://firefox-source-docs.mozilla.org/l10n/migrations/index.html),
+Thunderbird developers are working on migrating strings from legacy formats to
+Fluent. The process is very similar to how migrations are done for Firefox. The
+differences are detailed below.
+
+## Migration Recipes
+
+When part of Thunderbird’s UI is migrated to Fluent, a migration recipe should
+be included in the same patch that adds new strings to .ftl files. Recipies are
+stored in [comm-central](https://hg.mozilla.org/comm-central/file/tip/python/l10n/tb_fluent_migrations).
+After a patch with migrations landed, it will be run for all locales as part of
+the [Thunderbird Cross-Channel string quarantining process](cross_channel.md).
+
+Be sure to read [Migrating Legacy Formats](https://firefox-source-docs.mozilla.org/l10n/migrations/legacy.html)
+along with the below example.
+
+The migration recipe’s filename should start with a reference to the associated
+bug number, and include a brief description of the bug, e.g. `bug_1805746_calendar_view.py`
+for the below example.
+
+### Example: Migrate Multiple DTD strings to Fluent
+
+Often, strings are migrated as part of ongoing UI work to convert XUL code
+to HTML. Multiple DTD strings may convert to a single Fluent string with
+attributes. It really depends on the document structure and what the UI changes
+are doing.
+
+**Legacy strings are in `comm/calendar/locales/en-US/chrome/calendar/calendar.dtd`**
+
+```dtd
+<!ENTITY calendar.day.button.tooltip            "Switch to day view" >
+<!ENTITY calendar.day.button.label              "Day" >
+```
+
+**The (simplified) XUL code**
+
+```xml
+<radio id="calendar-day-view-button"
+       label="&calendar.day.button.label;"
+       tooltiptext="&calendar.day.button.tooltip;" />
+```
+
+**The new HTML**
+
+```html
+<button id="calTabDay" data-l10n-id="calendar-view-toggle-day"></button>
+```
+
+**The new FTL string**
+
+```fluent
+calendar-view-toggle-day = Day
+  .title = Switch to day view
+```
+
+**Renders as:**
+
+```html
+<button id="calTabDay" title="Switch to day view">Day</button>
+```
+
+This case migrates two DTD strings, `calendar.day.button.label` and `calendar.day.button.tooltip`
+to create a single FTL string, `calendar-view-toggle-day`, with one (`title`)
+attribute.
+
+**The migration recipe:**
+
+```python
+# Any copyright is dedicated to the Public Domain.
+# http://creativecommons.org/publicdomain/zero/1.0/
+
+from fluent.migratetb.helpers import transforms_from
+from fluent.migratetb import COPY
+
+def migrate(ctx):
+    """Bug 1805746 - Update Calendar View selection part {index}."""
+    target = reference = "calendar/calendar/calendar-widgets.ftl"
+    source = "calendar/chrome/calendar/calendar.dtd"
+
+    ctx.add_transforms(
+        target,
+        reference,
+        transforms_from(
+            """
+calendar-view-toggle-day = { COPY(from_path, "calendar.day.button.label") }
+    .title = { COPY(from_path, "calendar.day.button.tooltip") }
+""",
+            from_path=source,
+        ),
+    )
+```
+
+Migrations are Python modules, and implement
+a single `migrate(MigrationContext)` function. The `migrate()` function makes
+calls into `MigrationContext.add_transforms()`.
+
+The `add_transforms()` function takes three arguments:
+- `target_path`: Path to the target l10n file
+- `reference_path`: Path to the reference (en-US) file
+- A list of Transforms, the `source_path` (legacy translated strings file) is
+  set here
+
+```{note}
+For Thunderbird migrations, the target and reference path are the same.
+```
+
+Transforms are rather dense AST nodes. See
+[Transforms](https://firefox-source-docs.mozilla.org/l10n/migrations/overview.html#transforms)
+for the exact details.
+
+There are some helper functions that simplify creating the ASTs. The above example uses the
+`transforms_from()` helper function. It is equivalent to:
+
+```python
+target = reference = "calendar/calendar/calendar-widgets.ftl"
+source = "calendar/chrome/calendar/calendar.dtd"
+
+ctx.add_transforms(
+    target,
+    reference,
+    [
+        FTL.Message(
+            id=FTL.Identifier("calendar-view-toggle-day"),
+            value=COPY(source, "calendar.day.button.label"),
+            attributes=[
+                FTL.Attribute(
+                    id=FTL.Identifier("title"),
+                    value=COPY(
+                        source,
+                        "calendar.day.button.tooltip"
+                    )
+                )
+            ]
+        )
+    ]
+)
+```
+
+`transforms_from()` allows copying reference FTL strings, and replacing the value
+of each message with a `COPY` Transform that copies values from the DTD file at
+`from_path`.
+
+There are other Transforms like `COPY`. See
+[Migrating Legacy Formats](https://firefox-source-docs.mozilla.org/l10n/migrations/legacy.html)
+for usage information.
+
+### Thunderbird migration helpers
+
+The `REPLACE` works with `transforms_from` if provided the extra context that
+it needs.
+
+Starting with `aboutDialog.dtd` containing:
+
+```xml
+<!ENTITY update.updateButton.label3               "Restart to update &brandShorterName;">
+```
+
+```python
+from fluent.migratetb.helpers import TERM_REFERENCE, transforms_from
+
+# This can't just be a straight up literal dict (eg: {"a":"b"}) because the
+# validator fails... so make it a function call that returns a dict.. it works
+about_replacements = dict({
+    "&brandShorterName;": TERM_REFERENCE("brand-shorter-name"),
+})
+
+
+def migrate(ctx):
+    """Bug 1816532 - Migrate aboutDialog.dtd strings to Fluent, part {index}"""
+    target = reference = "mail/messenger/aboutDialog.ftl"
+    source = "mail/chrome/messenger/aboutDialog.dtd"
+
+    ctx.add_transforms(
+        target,
+        reference,
+        transforms_from(
+          """
+update-update-button = { REPLACE(source, "update.updateButton.label3", about_replacements) }
+    .accesskey = { COPY(source, "update.updateButton.accesskey") }
+""", source=source, about_replacements=about_replacements))
+```
+
+The resulting `aboutDialog.ftl` will get:
+
+```ftl
+update-update-button = Restart to update { -brand-shorter-name }
+    .accesskey = R
+```