Best practices in docs translation (original) (raw)

In the Indonesian translation team, we’re looking into making a style guide for translators. My assumption is that translation teams from other languages have wrestled with similar issues about how to translate technical terms. It also seems reasonable to suppose that some of the insights gained from that process could be generally relevant, rather than only applying to whatever language they are working in. If those insights were compiled in a reference document, they would potentially be useful to all teams, both now and in the future.

That said, the purpose of this post is twofold:

  1. To invite any coordinators or translators to share their insights or describe the problems they’ve encountered
  2. To gauge interest in creating a general “best practices” sort of document to serve as a guide for anyone looking to get involved in translating the docs.

What does everyone think?

irvan-putra (Irvan Putra) June 4, 2025, 3:19pm 2

I think this is great (well I am in that Indonesian team myself, haha), because I wonder how is it going at other language teams.

Standre (Simon Saint-André) June 4, 2025, 11:34pm 3

The spanish translation team has a Contributing guide (in Spanish)

It has instructions for translators, plus general guidelines, tips for reviewers and a glossary of commonly translated terms, to maintain consistency

nedbat (Ned Batchelder) June 5, 2025, 9:58am 4

The devguide would be a fine home for general guidelines that apply to all translations.

Python docs transifex documentation has some transifex use guidelines and translation guide lines (e.g. what to do with placeholders).

W3C also has a long document with broader guidelines, somewhat aimed at the people writing the English docs to make them easier to translate in the future.

The devguide would be a fine home for general guidelines that apply to all translations.

A page for people looking to contribute to existing translations would probably be a good idea, rather than extending the current coordinator focused doc.

willingc (Carol Willing) June 13, 2025, 7:56pm 6

Thanks for getting started on your draft PR for the devguide that splits out coordinators and translators. I like the approach. :sunny: