Skip to content

Instantly share code, notes, and snippets.

@flodolo
Created June 8, 2026 06:57
Show Gist options
  • Select an option

  • Save flodolo/cf8bf224b489df3ef51bc21c92d32d43 to your computer and use it in GitHub Desktop.

Select an option

Save flodolo/cf8bf224b489df3ef51bc21c92d32d43 to your computer and use it in GitHub Desktop.
Fix l10n docs
diff --git a/intl/l10n/docs/fluent/review.md b/intl/l10n/docs/fluent/review.md
index febf7af2bc59..5ab292812aca 100644
--- a/intl/l10n/docs/fluent/review.md
+++ b/intl/l10n/docs/fluent/review.md
@@ -14,7 +14,7 @@ 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](./tutorial.html) about Fluent.
-[Herald] is used to set the group [fluent-reviewers] as blocking reviewer for
+[Herald](https://phabricator.services.mozilla.com/herald/) is used to set the group [fluent-reviewers](https://phabricator.services.mozilla.com/tag/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.
@@ -147,7 +147,7 @@ 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](https://github.com/projectfluent/fluent.js/wiki/DOM-Overlays#text-level-elements)
dedicated to DOM overlays.
-This information is not relevant if your code is using [fluent-react], where
+This information is not relevant if your code is using [fluent-react](https://github.com/projectfluent/fluent.js/wiki/React-Bindings), where
DOM overlays [work differently](https://github.com/projectfluent/fluent.js/wiki/React-Overlays).
## Message References
@@ -181,7 +181,7 @@ will need to be updated anyway.
## Terms
-Fluent supports a specific type of message, called [term]. Terms are similar
+Fluent supports a specific type of message, called [term](https://projectfluent.org/fluent/guide/terms.html). 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.
@@ -298,8 +298,3 @@ content.
Documentation on how to write and test migration recipes is available in [this
page](./fluent_migrations.html).
-
-[fluent-react]: https://github.com/projectfluent/fluent.js/wiki/React-Bindings
-[fluent-reviewers]: https://phabricator.services.mozilla.com/tag/fluent-reviewers/
-[herald]: https://phabricator.services.mozilla.com/herald/
-[term]: https://projectfluent.org/fluent/guide/terms.html
diff --git a/intl/l10n/docs/fluent/tutorial.md b/intl/l10n/docs/fluent/tutorial.md
index 856a8b652735..71011e861279 100644
--- a/intl/l10n/docs/fluent/tutorial.md
+++ b/intl/l10n/docs/fluent/tutorial.md
@@ -21,7 +21,7 @@ uses Fluent for localization.
## Using Fluent in Gecko
-[Fluent] is a modern localization system introduced into
+[Fluent](https://projectfluent.org/) is a modern localization system introduced into
the Gecko platform with a focus on quality, performance, maintenance and completeness.
The legacy DTD system is deprecated, and Fluent should be used where possible.
@@ -37,13 +37,13 @@ Guidelines for the review process are available [here](./fluent_review.html).
To lighten the burden on reviewers, please take a moment to review some
best practices before submitting your patch for review.
-- [ProjectFluent Good Practices for Developers]
-- [Mozilla Localization Best Practices For Developers]
+- [ProjectFluent Good Practices for Developers](https://github.com/projectfluent/fluent/wiki/Good-Practices-for-Developers)
+- [Mozilla Localization Best Practices For Developers](https://mozilla-l10n.github.io/documentation/localization/dev_best_practices.html)
## Major Benefits
Fluent [ties tightly](https://github.com/projectfluent/fluent/wiki/Fluent-and-Standards) into the domain of internationalization
-through [Unicode], [CLDR] and [ICU].
+through [Unicode](https://www.unicode.org/), [CLDR](http://cldr.unicode.org/) and [ICU](http://site.icu-project.org/).
More specifically, the most observable benefits for each group of consumers are
@@ -84,7 +84,7 @@ new-tab-open = Open New Tab
But the FTL file format is significantly more powerful and the additional features
quickly add up. In order to familiarize yourself with the basic features,
-consider reading through the [Fluent Syntax Guide] to understand
+consider reading through the [Fluent Syntax Guide](https://projectfluent.org/fluent/guide/) to understand
a more complex example like:
```fluent
@@ -132,7 +132,7 @@ identifiers generated at run-time from external sources – that make this impra
In order to ensure the quality of the output, a lot of checks and tooling
is part of the build system.
-[Pontoon], the main localization tool used to translate Firefox, also supports
+[Pontoon](https://pontoon.mozilla.org/), the main localization tool used to translate Firefox, also supports
Fluent and its features to help localizers in their work.
(fluent-tutorial-social-contract)=
@@ -599,7 +599,7 @@ fallback works.
### Installing Nightly in a different locale
-Localized Nightly builds are listed on [firefox.com].
+Localized Nightly builds are listed on [firefox.com](https://www.firefox.com/en-US/download/all/desktop-nightly/).
### Installing language packs on local builds
@@ -614,7 +614,7 @@ However, if you really need to use this, you can:
1. Open `about:config` and flip the `intl.multilingual.enabled` and
`intl.multilingual.liveReload` preferences to `true`
-2. Open [the FTP listing for langpacks] and click the XPI file corresponding
+2. Open [the FTP listing for langpacks](https://ftp.mozilla.org/pub/firefox/nightly/latest-mozilla-central-l10n/linux-x86_64/xpi/) and click the XPI file corresponding
to your language and nightly version (note that, especially around merge days,
multiple versions may be present).
@@ -639,11 +639,11 @@ Instructions on how to build localization repacks are available on {doc}`/build/
### Including specific localization repacks to a Try Server push
-Instructions are available in the [Firefox L10N FAQs].
+Instructions are available in the [Firefox L10N FAQs](https://mozilla-l10n.github.io/documentation/products/firefox_desktop/firefox_l10n_faqs.html#how-can-i-test-a-different-locale).
### Finding a regression in a localized build
-You can run [mozregression] with localized builds!
+You can run [mozregression](https://mozilla.github.io/mozregression/) with localized builds!
At the commandline, if you wanted to find a regression in a Dutch (`nl`)
build, you could run something like::
@@ -711,19 +711,3 @@ L10nRegistry is our resource management service. It
maintains the state of resources packaged into the build and language packs,
providing an asynchronous iterator of {js}`FluentBundle` objects for a given locale set
and resources that the {js}`Localization` class uses.
-
-[cldr]: http://cldr.unicode.org/
-[firefox l10n faqs]: https://mozilla-l10n.github.io/documentation/products/firefox_desktop/firefox_l10n_faqs.html#how-can-i-test-a-different-locale
-[firefox preferences]: https://bugzilla.mozilla.org/show_bug.cgi?id=1415730
-[firefox.com]: https://www.firefox.com/en-US/download/all/desktop-nightly/
-[fluent]: https://projectfluent.org/
-[fluent syntax guide]: https://projectfluent.org/fluent/guide/
-[icu]: http://site.icu-project.org/
-[mozilla localization best practices for developers]: https://mozilla-l10n.github.io/documentation/localization/dev_best_practices.html
-[mozregression]: https://mozilla.github.io/mozregression/
-[pontoon]: https://pontoon.mozilla.org/
-[projectfluent good practices for developers]: https://github.com/projectfluent/fluent/wiki/Good-Practices-for-Developers
-[system add-ons]: https://bugzilla.mozilla.org/show_bug.cgi?id=1425104
-[the ftp listing for langpacks]: https://ftp.mozilla.org/pub/firefox/nightly/latest-mozilla-central-l10n/linux-x86_64/xpi/
-[unicode]: https://www.unicode.org/
-[unprivileged contexts]: https://bugzilla.mozilla.org/show_bug.cgi?id=1407418
diff --git a/intl/l10n/docs/migrations/index.md b/intl/l10n/docs/migrations/index.md
index 659ddad19678..bcb250d4807d 100644
--- a/intl/l10n/docs/migrations/index.md
+++ b/intl/l10n/docs/migrations/index.md
@@ -17,11 +17,11 @@
Firefox is a project localized in over 100 languages. As the code for existing
features moves away from the old localization systems and starts using
-[Fluent], we need to ensure that we don’t lose existing translations, which
+[Fluent](http://projectfluent.org/), we need to ensure that we don’t lose existing translations, which
would have the adverse effect of forcing contributors to localize hundreds of
strings from scratch.
-[Fluent Migration] is a Python library designed to solve this specific problem:
+[Fluent Migration](https://github.com/mozilla/fluent-migrate) is a Python library designed to solve this specific problem:
it allows to migrate translations from `.properties` and other legacy file formats,
not only moving strings and transforming them as needed to adapt to the `FTL`
syntax, but also replicating "blame" for each string in VCS.
@@ -53,6 +53,3 @@ write the migration recipes:
> - Bryan Olsson (:bolsson)
> - Francesco Lodolo (:flod)
> - Eemeli Aro (:eemeli)
-
-[fluent]: http://projectfluent.org/
-[fluent migration]: https://github.com/mozilla/fluent-migrate
diff --git a/intl/l10n/docs/migrations/legacy.md b/intl/l10n/docs/migrations/legacy.md
index df5607271e55..de5f8bf502eb 100644
--- a/intl/l10n/docs/migrations/legacy.md
+++ b/intl/l10n/docs/migrations/legacy.md
@@ -24,8 +24,8 @@ find a number of specialized functionalities here.
To assist with legacy format migrations, some scripting tools are provided:
-> - [XUL+DTD to Fluent]
-> - [.properties to Fluent]
+> - [XUL+DTD to Fluent](https://github.com/zbraniecki/convert_xul_to_fluent)
+> - [.properties to Fluent](https://github.com/mozilla/properties-to-ftl)
When creating a migration, one or both of these tools may provide a good
starting point for manual work by automating at least a part of the migration,
@@ -575,6 +575,3 @@ use-current-pages =
""", main_dtd="browser/chrome/browser/preferences/main.dtd"
)
```
-
-[.properties to fluent]: https://github.com/mozilla/properties-to-ftl
-[xul+dtd to fluent]: https://github.com/zbraniecki/convert_xul_to_fluent
diff --git a/intl/l10n/docs/migrations/localizations.md b/intl/l10n/docs/migrations/localizations.md
index 0f5a1a2f7f69..c0167bc3b54c 100644
--- a/intl/l10n/docs/migrations/localizations.md
+++ b/intl/l10n/docs/migrations/localizations.md
@@ -21,7 +21,7 @@ strings for all 100+ localizations:
> - New Fluent strings land in `mozilla-firefox`, together with a migration
> recipe.
-> - New strings are added to an `update` branch of [firefox-l10n-source],
+> - New strings are added to an `update` branch of [firefox-l10n-source](https://github.com/mozilla-l10n/firefox-l10n-source/),
> a unified repository including strings for all shipping versions of Firefox,
> and used as a buffer before exposing strings to localizers.
> - Migration recipes are run against all l10n subfolders, migrating strings
@@ -34,13 +34,10 @@ patches containing migrations land after the first.
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](https://github.com/flodolo/fluent-migrations) .
:::{tip}
A script to run migrations on all l10n repositories is available in [this
-repository][this repository], automating part of the steps described for manual testing, and
+repository](https://github.com/flodolo/fluent-migrations), automating part of the steps described for manual testing, and
it could be adapted to local testing.
:::
-
-[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.md b/intl/l10n/docs/migrations/testing.md
index 90a27c1ef44b..f0c0a9a8cdcf 100644
--- a/intl/l10n/docs/migrations/testing.md
+++ b/intl/l10n/docs/migrations/testing.md
@@ -152,7 +152,7 @@ languages.
## firefox-l10n-source repository
-[firefox-l10n-source] is a unified repository including strings for all
+[firefox-l10n-source](https://github.com/mozilla-l10n/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
@@ -171,5 +171,3 @@ such as checking out previous commits or adding strings manually. You can also f
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/
diff --git a/intl/l10n/docs/overview.md b/intl/l10n/docs/overview.md
index 90382e31f051..af88b625ba92 100644
--- a/intl/l10n/docs/overview.md
+++ b/intl/l10n/docs/overview.md
@@ -13,7 +13,7 @@ of Mozilla software into over 100 locales.
The exact process of localization management differs from project to project, but
in the case of Gecko applications, the localization is primarily done via a web localization
-system called [Pontoon] and stored in the [firefox-l10n] GitHub repository.
+system called [Pontoon](https://pontoon.mozilla.org/) and stored in the [firefox-l10n](https://github.com/mozilla-l10n/firefox-l10n) GitHub repository.
Developers are expected to keep their code localizable using localization
and internationalization systems, and also serve as localizers into the `en-US` locale
@@ -21,7 +21,7 @@ which is used as the `source` locale.
In between the developers and localizers, there's a sophisticated ecosystem of tools,
tests, automation, validators and other checks on one hand, and management, release,
-community and quality processes facilitated by the [Localization Team], on the other.
+community and quality processes facilitated by the [Localization Team](https://mozilla-l10n.github.io/introduction/team.html), on the other.
## Content vs. UI
@@ -77,10 +77,10 @@ into `mozilla-central`.
### 4) Exposure in `firefox-l10n-source`
Once the patch lands in `mozilla-central`, strings won't be exposed to localization
-until they are merged into [firefox-l10n-source], a unified repository that includes
+until they are merged into [firefox-l10n-source](https://github.com/mozilla-l10n/firefox-l10n-source), a unified repository that includes
strings for all shipping versions of Firefox (nightly, beta, release, ESR, etc.).
-Twice a day, automation in this repository extracts new strings from [gecko-dev]
+Twice a day, automation in this repository extracts new strings from [gecko-dev](https://github.com/mozilla/gecko-dev)
into a separate `update` branch. This branch acts as a buffer to avoid exposing
potential issues to over 100 locales. The Localization Team will take a final look at the
localizability of the introduced strings. In case of issues, developers might be
@@ -99,7 +99,7 @@ Firefox with incomplete translations falling back on a backup locale in case of
a missing string.
When translation completes in Pontoon, the final localized strings are stored in
-[firefox-l10n].
+[firefox-l10n](https://github.com/mozilla-l10n/firefox-l10n).
### 6) String updates
@@ -122,7 +122,7 @@ is requested to update the l10n string ID.
The latter is considered a change in the social contract between the developer and
the localizer and an update to the ID is expected.
-In case of [Fluent], any changes to the structure of the message such as adding/removing
+In case of [Fluent](https://projectfluent.org/), any changes to the structure of the message such as adding/removing
attributes also requires an update of the ID.
The new ID will be recognized by the l10n tooling as untranslated, and the old one
@@ -165,7 +165,7 @@ and limitations of older systems.
It's well suited for the modern web development cycle, providing a number of localization
features including a good internationalization model and strong bidirectionality support.
-To learn more about Fluent, follow the [Fluent for Firefox Developers] guide.
+To learn more about Fluent, follow the [Fluent for Firefox Developers](./fluent/tutorial.html) guide.
### StringBundle
@@ -175,10 +175,3 @@ and then retrieved from there via imperative calls.
The system provides external positional arguments which can be placed into the string.
Adding new StringBundle messages should only be done after serious consideration.
-
-[firefox-l10n]: https://github.com/mozilla-l10n/firefox-l10n
-[firefox-l10n-source]: https://github.com/mozilla-l10n/firefox-l10n-source
-[fluent for firefox developers]: ./fluent/tutorial.html
-[gecko-dev]: https://github.com/mozilla/gecko-dev
-[localization team]: https://mozilla-l10n.github.io/introduction/team.html
-[pontoon]: https://pontoon.mozilla.org/
diff --git a/intl/l10n/docs/singlel10nsource.md b/intl/l10n/docs/singlel10nsource.md
index 639a21a4e532..48b01394b113 100644
--- a/intl/l10n/docs/singlel10nsource.md
+++ b/intl/l10n/docs/singlel10nsource.md
@@ -16,20 +16,20 @@ localization to be as complete as possible for each version.
The process to tackle these follows these steps:
-- Create resource to localize, [firefox-l10n-source].
+- Create resource to localize, [firefox-l10n-source](https://github.com/mozilla-l10n/firefox-l10n-source).
- Review updates to that resource in a *quarantine*.
- Expose a known good state of that resource to localizers.
- Get content localized in Pontoon.
-- Write localizations back to [firefox-l10n].
+- Write localizations back to [firefox-l10n](https://github.com/mozilla-l10n/firefox-l10n).
- Get localizations into the builds.
## firefox-l10n-source repository
-[firefox-l10n-source] acts as a unified source string repository for all
+[firefox-l10n-source](https://github.com/mozilla-l10n/firefox-l10n-source) acts as a unified source string repository for all
shipping Firefox versions (nightly, beta, release, ESR, etc.).
The repository consists of two branches, `main` and `update`.
@@ -50,10 +50,7 @@ or copy that should be improved.
## firefox-l10n repository
-[firefox-l10n] acts as the source of truth of all localized strings. Once
+[firefox-l10n](https://github.com/mozilla-l10n/firefox-l10n) acts as the source of truth of all localized strings. Once
the translation of a string is completed in Pontoon, the content is stored
in the associated sub-directory for each locale. These strings are then used
during build to create builds and langpacks for all shipping Firefox locales.
-
-[firefox-l10n]: https://github.com/mozilla-l10n/firefox-l10n
-[firefox-l10n-source]: https://github.com/mozilla-l10n/firefox-l10n-source
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment