Translation
Plan translation from the start of your documentation project: tackle it early to cut costs and delivery times, translate modular content in parallel with writing, and organize source repositories language-first.
Definition
Section titled “Definition”Translation considerations must be addressed early in the editorial process, as they impact both the editorial style and the organization of repositories.
Why it matters
Section titled “Why it matters”There is no one-size-fits-all solution: delivering information in multiple languages requires ongoing oversight. However, addressing translation constraints early in the process and using an appropriate methodology can enhance quality and reduce costs and delivery times for multilingual versions. Translation should be integrated into the document workflow. Additionally, it is essential to ensure effective communication between technical writers, engineers, subject matter experts, designers, and translators.
If documentation is modular, translation can occur concurrently with writing, thereby reducing delivery times.
Parallelization of Writing and Translation
Key principles
Section titled “Key principles”Separate languages at the root
Section titled “Separate languages at the root”Regarding the organization of source file repositories, is it preferable to position the language directories before or after the document project directories? In other words, should the structure be as follows:
Language first
- english
- product 1
- product 2
- french
- product 1
- product 2
or like this:
Product first
- product 1
- english
- french
- product 2
- english
- french
In most situations, it is advisable to distinguish languages as early as possible. Using software development terminology, creating a translation of a content set is akin to creating a branch of that set. It is easier to manage a BranchA parallel line of work in a version-control system: changes made on a branch stay isolated until they are reviewed and merged back into the main line, so several writers, releases or languages can progress at the same time.View in glossary → from its root than from its ramifications, making it more practical to handle complete directories, especially when providing them to translators, rather than using a set of subdirectories.
Track updates: a translation is a fork
Section titled “Track updates: a translation is a fork”Once translation is completed, changes to either the source or translated version cannot be automatically mirrored. Continuing with software terminology, the new branch is a fork: modifications in one cannot be automatically reflected in the other. Therefore, to offer the same information in different languages, it is essential to effectively track updates to the original version.
Continuous localization
Section titled “Continuous localization”Version controlRecording every change to a set of files so that any earlier state can be restored, changes can be compared, and several people can work in parallel. Git is the most widely used version-control system; docs-as-code keeps documentation under version control next to the product code.View in glossary → makes this tracking concrete. When sources are text files in Git, the CommitA recorded snapshot of changes in a Git repository, with an author, a date, and a message explaining the change. Commits form the project history that branches start from and that reviewers and translators compare.View in glossary → history shows exactly which source files changed since the last translation, so translators receive only the changes instead of a full document set, and translation can follow each release rather than lag behind it.
| Without version control | With Git | |
|---|---|---|
| Finding what changed | Updates to the original version must be tracked | The commit history shows which source files changed |
| What translators receive | A full document set | Only the changes |
| When translation happens | Lags behind the release | Follows each release |
| A locale-first RepositoryThe place where a documentation team keeps its sources: shared folders, a CMS database, or a version-control system such as Git, which also stores the complete history of every file.View in glossary → layout (see the repository structure example) keeps each language a complete tree that can be built and checked on its own. |
Machine translation and AI-assisted translation can reduce the effort per update, but their output still needs review by someone who knows both the language and the product.
Related articles
Section titled “Related articles”- Content creation
- Git: from file to content
- Formats and tools
- Case study: NuFirewall documentation: translating conref-based DITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary → content
- Case studies in using DITA XML
Related reading
Section titled “Related reading”- An AI-based workflow to translate legacy content - automating translation of legacy technical docs while keeping a human in the loop.