[Framework] Put i18n logic in place #110
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Overhaul of the JS code to handle localized versions of roadmap documents. As discussed in w3c#68, the code assumes that the following naming convention is used for all localized files: [name].[lang].[ext] English versions of the files are assumed to be named: [name].[ext] To determine the language of the HTML page to render, the code checks the `lang` attribute on the `<html>` tag. If it not set, it tries to extract the language from the page name (`window.location.pathname`), using the above convention. If if not set, English (`en`) is assumed. The page tries to load localized versions of all files. If not found, it falls back to the English versions. The code issues warnings on the console when it cannot find localized versions of a given file (in some cases, we may not need localized versions, so warnings may not be warranted. However they are useful during development to understand what still needs to be translated). Files that may (and often should!) be localized are: 1. `toc.json`: the labels, descriptions and URLs should be localized 2. `*.html`: the actual contents of the roadmap obviously need to be localized. Note the need to update the `lang` attribute of the `<html>` tag, otherwise the code will consider that the page is in English. 3. `js/template-table-*.html`: the HTML templates used for generated tables. (These templates used to be hardcoded in `generate.js`) 4. `js/translations.[lang].json`: the translations of features, group names, spec titles, and labels that are needed to render the roadmaps. The file is a semi-flat mapping table between the English string and the translated string. First level properties are: "features" for feature names that appear in data files, "groupNames" for translations of group names, "specTitles" for translations of spec titles, "labels" for all other translations. For instance, the beginning of a `js/translations.fr.json` document could be: ``` { "labels": { "shipped": "C'est en prod!", "experimental": "On déboggue", "indevelopment": "On y travaille", "consideration": "On y réfléchit", "N/A": "Non renseigné", "in": "dans" }, "features": { "audio element": "La balise audio", "picture element": "La balise picture" }, "groupNames": { "CSS Working Group": "Le groupe de travail CSS" }, "specTitles": { "Magnetometer": "Magnétomètre" } } ``` The overhaul also adds support for merging features in generated tables when they use the same "data-feature", even if they appear in different parts of the documents (w3c#73).
|
Another note for later: there's a little bit of code duplicated between |
|
Thank you! |
This was referenced Oct 21, 2017
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Overhaul of the JS code to handle localized versions of roadmap documents.
As discussed in #68, the code assumes that the following naming convention is used for all localized files:
[name].[lang].[ext]English versions of the files are assumed to be named:
[name].[ext]To determine the language of the HTML page to render, the code checks the
langattribute on the<html>tag. If it not set, it tries to extract the language from the page name (window.location.pathname), using the above convention. If not set, English (en) is assumed.The page tries to load localized versions of all files. If not found, it falls back to the English versions. The code issues warnings on the console when it cannot find localized versions of a given file (in some cases, we may not need localized versions, so warnings may not be warranted. However they are useful during development to understand what still needs to be translated).
Files that may (and often should!) be localized are:
toc.json: the labels, descriptions and URLs should be localized*.html: the actual contents of the roadmap obviously need to be localized. Note the need to update thelangattribute of the<html>tag, otherwise the code will consider that the page is in English.js/template-table-*.html: the HTML templates used for generated tables. (These templates used to be hardcoded ingenerate.js)js/translations.[lang].json: the translations of features, group names, spec titles, and labels that are needed to render the roadmaps. The file is a semi-flat mapping table between the English string and the translated string. First level properties are: "features" for feature names that appear in data files, "groupNames" for translations of group names, "specTitles" for translations of spec titles, "labels" for all other translations.For instance, the beginning of a
js/translations.fr.jsondocument could be:The overhaul also adds support for merging features in generated tables when they use the same "data-feature", even if they appear in different parts of the documents (#73).
A couple of notes for later:
[name].[ext]files for English to be able to continue to use GitHub Pages easily. However, if published as-is, note that this prevents content negotiation (index.htmlcannot both mean "the localized version for the user" and "the English version"), so we may want to revisit that later on.