Translators' Guide

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.

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 HTML files are automatically generated by running npm run generate when the templates exist so do not need to be translated.
• Submit translations as pull requests. 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.
• A second speaker should ideally review the language and one of the regular maintainers (e.g. @rviscomi or @bazzadp) 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. The text should be multi-line to make this easier.
• 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)
• When language convention uses spaces, where these do not exist in English, but they should not be separated by line breaks, then use  . 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 % 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.

Translation status

	English	Spanish	French	Japanese	Russian	Italian	Arabic	Portuguese
JavaScript	✓	✓
CSS.	✓	✓		✓
Markup	✓	✓	✓	✓
Media	✓
Third Parties	✓		✓	✓
Fonts	✓
Performance	✓	✓		✓
Security	✓			✓
Accessibility	✓			✓
SEO	✓		✓	✓
PWA	✓			✓
Mobile Web	✓			✓
Ecommerce	✓	✓		✓
CMS	✓		✓	✓
Compression	✓			✓
Caching	✓		✓	✓
CDN	✓			✓
Page Weight	✓			✓
Resource Hints	✓		✓
HTTP/2	✓			✓