MozillaWiki

MDN/Development/CompatibilityTables/Translation

< MDN‎ | Development‎ | CompatibilityTables
Revision as of 16:41, 6 November 2015 by Stephaniehobson (talk | contribs) (updated Localizing wiki-compat-table.js)

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.

{{EmbedCompatTable}} KumaScript macro

The EmbedCompatTable macro has some support for translations:

https://developer.mozilla.org/en-US/docs/Template:EmbedCompatTable

The page's locale will be used to lookup strings in langDictionary, 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,

  1. Copy the latest code from https://developer.mozilla.org/en-US/docs/Template:EmbedCompatTable to https://developer.allizom.org/en-US/docs/Template:EmbedCompatTable (the MDN staging environment)
  2. Copy the "en-US" entry of langDictionary, renaming it to the target locale
  3. Translate the strings in the new copy
  4. Try it out on staging, adding the {{EmbedCompatTable}} macro as needed
  5. When it is working, copy it back to the production version at https://developer.mozilla.org/en-US/docs/Template:EmbedCompatTable

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 once bug 1218902 is fixed.

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":

  1. Sign into https://browsercompat.herokuapp.com
  2. Go to the browsable API page: https://browsercompat.herokuapp.com/api/v1/browsers/6
  3. At the bottom, select the "Raw data" tab instead of "HTML form".
  4. 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:

https://browsercompat.herokuapp.com/api/v1/view_features/web-javascript-reference-global_objects-promise

if you want to force the JSON version, you can go to:

https://browsercompat.herokuapp.com/api/v1/view_features/web-javascript-reference-global_objects-promise

Translating the page involves:

  1. Find resources with strings needing translation in view_features
  2. Using the above procedure to translate the resource
  3. 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.

Retrieved from "https://wiki.mozilla.org/index.php?title=MDN/Development/CompatibilityTables/Translation&oldid=1104591"