xrpl-dev-portal
xrpl-dev-portal copied to clipboard
XRPLF
Translation Plan
Translation Plans
We would like to translate the XRP Ledger Dev Portal to several languages, starting with Japanese. In each case, we will add translated pages piecemeal as they become available.
This page describes how we would organize and present the translated content.
User Experience
Users browsing the dev portal receive the English language version by default. When a page is available in other languages, a section in the right sidebar (next to the "In this Page" listing) indicates which languages it is available in. Each language name is presented in its native language. For example, the sidebar would list "Español", not "Spanish".
When a user clicks a language in the sidebar, it takes them to an alternate-language version of the same page in the same site. The URL of the language pages changes to include a language code per IETF BCP47. For example, "en" for English, "es" for Spanish, "ja" for Japanese, "zh-CN" for Simplified Chinese, "zh-TW" for Traditional Chinese (as used in Taiwan), and so on.
Pages in the alternate-language version of a site retain their (english, ASCII) HTML filenames. For example:
English: https://developers.ripple.com/xrp-ledger-overview.html
Japanese: https://developers.ripple.com/ja/xrp-ledger-overview.html
English is the default because we are creating most if not all documents in English originally. Optionally we can set up a redirect on the web server to go from /en/* to /*.
While a user is viewing an alternate-language version of a site, all links to other documents go to the same-language versions if available. If those versions are not available, it falls back to an English-language version of the page with the foreign-language prefix. This allows a path from two translated pages to pass through an untranslated page. For example:
"Introduction" (ja version) → "Transaction Censorship Detection" (not translated; falls back to English) → "rippled Server Modes" (ja version)
Future feature: When a user is viewing an untranslated (that is, English-language) page from a non-English language view, the sidebar has a "Translate this page" link. This link leads to a GitHub editor where the user can create a translation of the page, using the English language source Markdown as a starting point. Or, if that's too difficult, the link goes to a set of instructions for how to contribute a translation.
Source Files
I propose a convention of keeping translated Markdown source files in the same folder as their untranslated counterparts, using the same file name except that the file extension is .{lang}.md instead of just .md, where {lang} is the langauge code. For example, xrp-ledger-overview.ja.md for Japanese and xrp-ledger-overview.zh-CN.md for Simplified Chinese.
Future feature: A "translation freshness checker" script could list all translated files that have been modified less recently than their English-language counterparts. (This doesn't necessarily mean those files are out of date, as the fixes may be English-specific, but it provides a starting point for finding translations that need to be refreshed.)
dactyl-config.yml Changes
The "local" target will be renamed "en".
The first time a translation in a new language is made available, we create a new target whose short name is the language code for that language. The display name for the target is "XRP Ledger Dev Portal" followed by the display name of the language in parentheses. For example, for Japanese, the target's short name would be "ja" and the display name would be "XRP Ledger Dev Portal (日本語)". Each target will also have a lang property with the short name of the language.
When we create a new target, we add all untranslated pages from the "en" target to the new target. For translated pages, we add separate entries to the pages array that are used only by their language target.
Example:
# English-language version of a translated page
- md: concepts/introduction/xrp-ledger-overview.md
html: xrp-ledger-overview.html
funnel: Docs
doc_type: Concepts
category: Introduction
blurb: Get a quick and concise introduction to key features of the XRP Ledger.
targets:
- en
# Japanese-language version of a translated page
- md: concepts/introduction/xrp-ledger-overview.ja.md
html: xrp-ledger-overview.html
funnel: Docs
doc_type: Concepts
category: Introduction
blurb: TODO: Japanese blurb
targets:
- ja
# English version of an untranslated page
- md: concepts/introduction/intro-to-consensus.md
html: intro-to-consensus.html
funnel: Docs
doc_type: Concepts
category: Introduction
blurb: Develop a basic understanding of the XRP Ledger's consensus mechanism.
targets:
- en
- ja # Use the English version until it's translated.
Build System Changes
Each supported language is built as a separate target. Therefore, the deploy process must build each of them. After building English, the build/deploy system builds each other language to a subfolder of the target output folder, rather than building them to the target output folder directly.
Non-English targets use the same static content as the English-language version of the site. (They may reference differently-named image files, but those image files are stored in a single img/ folder that is shared across all translations.) Therefore, when building non-English targets, the build system uses the --no_static or -S flag of dactyl_build to skip copying the static content additional times.
The "all target link checker" script will need to be updated to build all language targets, then run the link checker once on the compiled output.
Template Changes
The templates will need several modifications to support various languages.
The base template will add appropriate meta tags and attributes to mark the language of the page.
When building any non-English tag, the path to the static assets must change to be based on the parent (English) directory rather than the current directory.
The document templates will need to be modified to display alternate translations of the page, probably in the right sidebar next to the "In this Page" content.
Graphics in Translations
Translated graphics can use the same file extension convention as Markdown source files. For example, a PNG file translated to Spanish would use the file extension .es.png, and would be stored alongside the English-language version in the img/ folder.
Because the translated pages are served from subdirectories, any references in their content Markdown to diagrams must use the parent (English) directory as a base for their paths.
The target definition for non-English languages can use a new custom Dactyl filter to automatically adjust source files so that diagrams can be linked similarly regardless of language. This way, the path to un-translated graphics is consistent across languages.
For example:
English: img/anatomy-of-a-ledger-complete.png
Japanese: img/anatomy-of-a-ledger-complete.ja.png → ../img/anatomy-of-a-ledger-complete.ja.png
(The → indicates the transformation that would be handled automatically by the filter.)
Now that the first pass of the Japanese translation is live, some next steps. Of course, the most important next step is to continue expanding and updating the translated docs, but there are other things we can do to improve the experience of using translated docs.
Auto-Detection
Javascript to read the user's preferred language from the web browser settings and navigate to that language by default (if it's one of the available languages). This probably needs to use a cookie or something in order to save the user's preferences. If they click a different language, it needs to remember not to redirect them back.
Improved Contribution Guidelines
The contribution info in the dev portal right now is extremely barebones. A contribution guide, with steps for how to add changes, would be good. Especially needed are instructions for how to add a new translation for a page that isn't translated yet, and instructions for adding a new language entirely.
Translate Dev Tools
Some of the text in the API tools comes from Javascript files. Those files themselves should be able to select from translations as well.
Export Strings Files
Rather than having everything in the dactyl-config.yml file, it would be ideal if the strings files could be separate imported files. This probably requires changes to Dactyl itself.
Some further updates.
Strings Files: The site now uses strings files & the Jinja localization plugin to manage translations within the (HTML) templates.
JavaScript files still don't have translation. We could probably use jQuery i18n or something along those lines to do something similar.
One of the biggest outstanding questions is around the process of tracking when the translations need to be updated. There should be a way to use Git to figure out which pages have had their English versions updated more recently than translations.
Also, it would be nice if the translation framework supported translating individual pages a little more easily. Right now you need to do a whole lot in the Dactyl config to add a new language target the first time you translate a page into that language.
