MDN/Development/CompatibilityTables/Translation
This page documents the current state of internationalization (i18n) and localization (l10n) of compatibility tables.
The browser compatibility API and the API-back compatibility tables are in alpha testing.
In the future, it will be a lot easier to translate strings. Some ideas are:
- If a table has non-localized strings, the JS will know it, and MDN visitors will be prompted to contribute a translation for that string.
- The contribution interface will provide a translation interface focused on an MDN page.
- The contribution interface will provide a translator interface, showing a high-level view of the translation state for a locale, and where the English variant has been updated since the local variant.
The work priorities are:
- Make it possible to translate strings, even if it is difficult or technical.
- Make it easy to translate strings, with useful interfaces
- Make it natural to translate strings, as a side-effect of viewing the site.
Contents
Viewing Translated Content
- If you are in the alpha group, you can see translated Compatibility tables on pages with the {{EmbedCompatTable}} macro on non-English pages. The easiest way to find these is to go to the template page, scroll to the bottom, select "Search for page that use Template:EmbedCompatTable to see examples...", and look for non-English pages.
- The L10n:CompatTable macro contains the UI strings used by the {{EmbedCompatTable}} macro.
- The importer has a preview of translated content, as seen by the API. Go to the importer, find the page you are interested in (for example Web/CSS/display, and use the links in the "Languages" section to see the content (partially) translated into that locale.
- When a feature has been committed to the API, you can view the API translated strings, such as https://browsercompat.herokuapp.com/view_feature/730 . This is driven by JavaScript, works identically to the importer's sample views, but works with the committed API data available for MDN pages.
- Another view of committed API data is at https://browsercompat.herokuapp.com/api/v1/view_features/730.html . This is driven by server-side templates, using a query-string parameter (such as lang=fr) to do server-side translation from API data.
{{EmbedCompatTable}} KumaScript macro
The EmbedCompatTable macro uses the L10n:CompatTable macro for translated strings:
https://developer.mozilla.org/en-US/docs/Template:L10n:CompatTable
The page's locale will be used to lookup strings, and use the locale's variants if available. This includes support text such as "Yes", "No" and "Partial" and feature text such as "Basic Support", "Experimental", and "Non-Standard".
Web/JavaScript/Reference/Global_Objects/Promise is a simple page:
Promise.resolve includes footnotes, which require localizations:
Adding a locale
To add a new locale, modify L10n:CompatTable to add your locale's translations. A safe way to do this:
- Copy the latest code from https://developer.mozilla.org/en-US/docs/Template:EmbedCompatTable and https://developer.mozilla.org/en-US/docs/Template:L10n:CompatTable to https://developer.allizom.org/en-US/docs/Template:EmbedCompatTable and https://developer.allizom.org/en-US/docs/Template:L10n:CompatTable (the MDN staging environment)
- Add your locale on the staging copy of L10n:CompatTable
- Try it out on staging, adding the {{EmbedCompatTable}} macro to target pages as needed
- When it is working, copy it back to the production version
wiki-compat-table.js
The compatibility tables are enhanced with JavaScript from wiki-combat-table.js, which includes some strings:
https://github.com/mozilla/kuma/blob/master/kuma/static/js/wiki-compat-tables.js
These are wrapped in gettext, such as gettext('Open').
This file includes the feedback dropdown at the top right corner.
Localizing wiki-compat-table.js
These can be localized in Pontoon or Verbatim the same way we do other interface strings.
API Localized Strings
The BrowserCompat API contains several localized strings, such as name and note in browsers:
{
"browsers": {
"id": "6",
"slug": "firefox_desktop",
"name": {
"en": "Firefox for Desktop"
},
"note": null,
"links": {
...
}
Localized strings can be optional (null is an allowed value), such as note above.
Strings can also marked as canonical, meaning that the string is the same in all locals. For example, in the resource for the Feature for the CSS property background, mdn_uri is a translated string (mapping locales to strings), but name is canonical and is specified as a string:
{
"features": {
"id": "655",
"slug": "web-css-background",
"mdn_uri": {
"en": "https://developer.mozilla.org/en-US/docs/Web/CSS/background",
"de": "https://developer.mozilla.org/de/docs/Web/CSS/background",
"es": "https://developer.mozilla.org/es/docs/Web/CSS/background",
"fr": "https://developer.mozilla.org/fr/docs/Web/CSS/background",
"it": "https://developer.mozilla.org/it/docs/Web/CSS/background",
"ja": "https://developer.mozilla.org/ja/docs/Web/CSS/background",
"ko": "https://developer.mozilla.org/ko/docs/Web/CSS/background",
"pl": "https://developer.mozilla.org/pl/docs/Web/CSS/background",
"pt-PT": "https://developer.mozilla.org/pt-PT/docs/Web/CSS/background",
"zh-CN": "https://developer.mozilla.org/zh-CN/docs/CSS/background"
},
"experimental": false,
"standardized": true,
"stable": true,
"obsolete": false,
"name": "background",
"links": {
...
}
Here are the localizable strings:
- browsers.name
- browsers.note (optional)
- versions.release_notes_uri (optional)
- versions.note (optional)
- features.mdn_uri (optional)
- features.name (optional, can be canonical)
- supports.note (optional)
- specifications.name
- specifications.uri
- sections.number (optional)
- sections.name (optional)
- sections.subpath (optional)
- sections.note (optional)
- maturities.name
Localizing API Strings
API strings can be localized by directly calling the API. The easiest way to do this (which still isn't very easy) is to use the browsable API. For example, to add "Firefox pour PC de bureau" as the French translation of "Firefox for Desktop":
- Sign into https://browsercompat.herokuapp.com
- Go to the browsable API page: https://browsercompat.herokuapp.com/api/v1/browsers/6
- At the bottom, select the "Raw data" tab instead of "HTML form".
- Enter the minimal JSON API to change the name, then select PATCH:
{
"browsers": {
"name": {
"en": "Firefox for Desktop",
"fr": "Firefox pour PC de bureau"
}
}
}
Some things to remember:
- The JSON must be valid. No trailing commas allowed. All strings must be wrapped in double quotes. Use http://jsonlint.com to check your code.
- The JSON must be in JSON-API format used in the v1 API (browsers -> name -> locales -> strings). This doesn't match the JSON sample in the Raw data field, which must be altered.
- All current locales and translations must be included, or they will be removed.
- You can just include the attribute you are changing, and other omitted attributes will be untouched.
- Whitespace doesn't matter, which can help when converting to the default raw data format to the JSON API format.
For example, the raw version looks like this:
{
"id": 6,
"slug": "firefox_desktop",
"name": {
"en": "Firefox for Desktop",
"fr": "Firefox pour PC de bureau"
},
"note": null,
"history": [
38,
37,
29,
20,
19,
18,
17,
16,
6
],
"history_current": 38,
"versions": [
67,
68,
69,
72,
...
]
}
Delete all but the name section...
"name": {
"en": "Firefox for Desktop",
"fr": "Firefox pour PC de bureau"
},
Remove the trailing comma:
"name": {
"en": "Firefox for Desktop",
"fr": "Firefox pour PC de bureau"
}
Insert the new translation, keeping track of commas:
"name": {
"en": "Firefox for Desktop",
"de": "Firefox für den PC",
"fr": "Firefox pour PC de bureau"
}
And then wrap it in a resource for the JSON API format:
{"browsers": {
"name": {
"en": "Firefox for Desktop",
"de": "Firefox für den PC",
"fr": "Firefox pour PC de bureau"
}
}}
In the future, the default Raw Data format will be the JSON API format, making this easier. And, shortly after, we'll have a web-based contribution interface which makes translations a lot easier.
Localizing an MDN page
When building a MDN page, the view_features interface is used. For example, the macro that place the API-backed table on Promise is:
{{ EmbedCompatTable("web-javascript-reference-global_objects-promise") }}
The API endpoint is:
if you want to force the JSON version, you can go to:
Translating the page involves:
- Find resources with strings needing translation in
view_features - Using the above procedure to translate the resource
- Force-refreshing the MDN page to call the API and regenerate the API-backed table.
For example, if you search for the string "en" (en wrapped in quotes), you'll find some already translated strings (features.mdn_uri and features.name for the main feature), as well as some untranslated strings:
...
"linked": {
"browsers": [
{
"id": "1",
"slug": "android",
"name": {
"en": "Android Browser"
},
"note": null,
"links": {
"history": [
"26",
"1"
],
"history_current": "26"
}
},
...
Most will be in the linked section, which are a list of resources linked to the main feature. Once you find a resource that needs translation, go to the browsable API for that resource (in this case, https://browsercompat.herokuapp.com/api/v1/browsers/1), and follow the above procedure to translate the string.
You can refresh the view_features endpoint to confirm that the strings are translated. Once you are happy with the translations, force-refresh the MDN page to regenerate the API-backed table.
In the future, code will be able to determine if a view_feature endpoint contains untranslated strings for a locale, and a web-based contribution interface will make it easier to translate the needed strings.
Maturity names
The Specification Table uses the Spec2 macro to translated specification maturities. The API processes this and SpecName to populate the Maturity and Specification resources.
There is not yet a macro like {{EmbedCompatTable}} for embedding API-backed specification tables in MDN.
To translate a Maturity into a new language:
- Update the Spec2 macro
- Ask jwhitlock to re-import the data (using tools/load_spec_data.py)
