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. We welcome all translation submissions.

Table of contents

• Commitment summary
  • How to join
• The translation process

Commitment summary

The 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 2021, 2020 and 2019, either for the unfinished translations in currently supported languages, or to start translating into a new language. This makes the content available to more and gets you familiar with the translation process setting you up to hit the ground running when new 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.

The translation process

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, 2020 Translation Progress, 2021 Translation Progress, and 2022 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.
• Preference is to translate the most recent content (i.e. the most recent years over previous years), but if a translator has a particular interest in a topic and wishes to translate older years, then that's fine too.
• 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. In fact there is a GitHub Action in place to check the line numbers match.
• 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. 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 Wikipedia links (or other links with '/en/' or 'https://en' in their URL). We try to convert markdown link syntax to HTML when editing the English chapters to make this easier for translators but may miss some links. For MDN, we link to the non-language specific page (without an hreflang) which will redirect as appropriate to the best fitting version at the time of click so they won't have an hreflang. Neither do Twitter links since they have translate functionality.
• 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).