Translators' Guide

Translators' Guide

Translators are a group of fluent multilingual technical writers who make the insights of the Web Almanac accessible to new audiences worldwide by translating the contents of the 20+ chapters.

Commitment summary

The 2020 translation process can start as early as October, when the website copy and chapter drafts are finalized. However, it's best to wait until everything is published in November to avoid last-minute content churn. Translations can be an iterative process in which one chapter gets translated at a time over the course of several months.

We are also still taking translations for 2019, either for the unfinished translations (French, Portuguese, Spanish and Simplified Chinese), to review the finished Japanese translation, or to start translating into a new language. This makes the 2019 content available to more and gets you familiar with the translation process setting you up to hit the ground running when the 2020 content is available to translate.

The time commitment per chapter is about 4 hours per chapter to translate and address feedback.

There are also fluent translation reviewers who look over the translated pull requests for correctness. The time commitment for these reviewers is approximately 1 hour per chapter.

How to join

Leave a comment in the Call for Translators issue.

---

We welcome all translation submissions.

All translation related work is marked with the Translation label so check if an issue already exists for any language you want to help with. We also track the language issues and status in the 2019 Translation Progress and 2020 Translation Progress wiki pages.

Below are the guidelines we are following for Translations. Note certain languages may have specific guidelines on top of these, which will be detailed in that language's issue.

• Open an issue for language translations and track the translations progress in that (example issue: #539). Assign other translators who are part of the team and "claim" a chapter to translate by putting your name against it.
• All translation related issues and pull requests should be marked with the Translation label.
• Translate each chapter's markdown and the non-chapters HTML template files. The chapter MD files are automatically converted to HTML versions by running npm run generate.
• Submit translations as pull requests (example translation pull request). Please include "Makes progress on XXX" in all pull requests (replacing XXX with the translation issue) so a link is created from the PR to that issue.
• We advise to merge main into the branch before opening the pull request, and periodically if the PR is taking some time to approve. We also advise not to translate using you own main branch on your fork. For more information see our Git Guide
• A second speaker should ideally review the language, plus one of the regular maintainers (e.g. @rviscomi or @tunetheweb) will also review from a technical side and then merge.
• Use the English chapters as the baseline.
• Please keep line numbers the same between translations. This will aid comparisons when reviewing pull requests and also allow those who don't speak the language to still make technical changes to the files for design or other reasons. So do not split the text into lines after 80 characters for example.
• Please raise an issue if there is something specific needed for a language so we can discuss best way of doing this (and feel free to suggest an approach!). For example for Arabic we added right to left support.
• English product names (Web Almanac, HTTP Archive) should remain in English but can be adjusted slightly to local version (e.g. Le Web Almanac rather than The Web Almanac). For some languages this rule may be ignored if there are language specific character sets (e.g. Japanese might use katakana, hiragana, or kanj rather than English if that makes more sense).
• Links to language-specific version of resources if available (e.g. MDN or Wikipedia, for example).
• Ideally add a hreflang="en" if a link points to an English article (e.g. when there is no language-specific version). This will put a (en) superscript entry after the link to inform the reader that the link points to an English article so they needn't bother clicking on it if they won't understand it. Note this will automatically happen for MDN and Wikipedia links (or other links with '/en/' or 'https://en' in their URL). Note also, this may require converting a link in markdown syntax to HTML syntax which we appreciate is extra effort so understand if translators do not want to take on this extra task. The translation itself is more important and this is a nice to have to be honest.
• When language convention uses spaces, where these do not exist in English, but they should not be separated by line breaks, then use non-breaking spaces (  or the unencoded version, which is probably cleaner rather than polluting the markdown with loads of   entries). For example in English we use 25% (with no space) but French uses 25 % (with a space). So in the French version it should be translated as 25 % or 25 % to prevent line breaks separating the 25 and the %. Similarly French normally puts a space before colons, whereas English does not.
• There will be differences and disagreements between translations. Languages are fluid and spoken in many different places and ways around the world. We will leave it to the translation teams to try to reach consensus. Where either phrasing could be used, the pull request author has final say (reviews are suggestions not dictates) but would strongly advise trying to get consensus. This project is for fun, and we're trying to reach more people by translating, so let's not lose sight over that a disagreement over best way to phrase something. If it helps I would advise the primary or most common dialect is used (e.g. French spoken in France, rather than in Canada) - even if this means swallowing pride about the incorrect use of "American English" when they didn't even invent the language! 😁
• Ideally use <i lang="en"></i> syntax when leaving a phrase untranslated and in English (e.g. <i lang="en">as-a-Service</i>). This is better for accessibility as otherwise screen-readers may not read content out correctly. Note do not over use this and any technical terms or commonly understood terms in that language do not need this (see this discussion(.