Internationalization (i18n)
Relevant source files
The following files were used as context for generating this wiki page:The internationalization (i18n) system for the Datadog documentation is built upon the Hugo static site generator's multilingual capabilities. It is designed to serve documentation in multiple languages, with American English (en_US) as the primary and default language. The system relies on a specific content organization, an external translation management process, and build-time scripts to handle dynamic content like API documentation.
The core principle of the i18n strategy is that English content is the source of truth. All translations are managed through an external translation service, and contributors are explicitly instructed not to edit translated files directly within the GitHub repository. Automated workflows are responsible for pulling updated translations from the service and committing them to the repository.
Sources: CONTRIBUTING.md:13-16, CLAUDE.md:30-31
Content Organization
The repository uses a directory-based system to separate content for different languages, which is a standard Hugo practice.
Sources: CLAUDE.md:27-28
Directory Structure
Each language has its own subdirectory within the content/ directory. English content resides in content/en/, while translated content is placed in directories named after their language codes.
The following diagram illustrates the content directory structure for languages.
Sources: CLAUDE.md:27-28, CONTRIBUTING.md:15-16
Supported Languages
The documentation supports several languages. The primary language for all new content and code comments is American English.
| Language | Code | Directory |
|---|---|---|
| English (American) | en_US | content/en/ |
| French | fr | content/fr/ |
| Japanese | ja | content/ja/ |
| Korean | ko | content/ko/ |
| Spanish | es | content/es/ |
Sources: CONTRIBUTING.md:13-16, CLAUDE.md:28
Translation Process and Contribution
The translation process is managed externally to ensure consistency and quality. Contributors should only modify the English source files.
Translation Workflow
- Content is written or updated in the English (
en) directory. - The documentation team sends the new or updated English content to an external translation service.
- The service translates the content into the supported languages.
- Automated workflows pull the translated content from the service and commit it to the corresponding language directories (
fr,ja,ko,es) in the GitHub repository.
This workflow is visualized in the following diagram.
Sources: CONTRIBUTING.md:15-16, CLAUDE.md:28, 38-39
Contribution Policy
A strict policy is in place regarding contributions to translated files: Do not contribute updates to translated files. Any necessary corrections must be reported to the documentation team, who will manage the fix through the external translation service. This ensures that the external service remains the single source of truth for all non-English content.
Sources: CONTRIBUTING.md:15-16, CLAUDE.md:38-39
Technical Implementation
The i18n system is implemented at various levels, from Hugo templates to build scripts that generate API documentation.
Templating and UI Strings
Hugo templates, located in layouts/, are designed to be language-aware. They use Hugo's built-in i18n functions and logic to render content correctly for the selected language.
The API documentation list page (layouts/api/list.html) provides a clear example. It performs the following i18n-related tasks:
- Checks the current page's language (
$.Page.Lang). - If the language is not English, it attempts to load translated data files, such as
translate_tags.[lang].jsonandtranslate_actions.[lang].json. - It uses the
i18nfunction to display translated UI strings (for example,i18n "overview"). - It constructs language-specific URLs for the navigation menu.
The following snippet from the API list template shows how it loads language-specific data.
{{/* layouts/api/list.html:40-47 */}}
{{ if ne $.Page.Lang "en"}}
{{ if (fileExists (print "data/api/" $apiVersion "/translate_tags." $.Page.Lang ".json")) }}
{{ $.Scratch.Set "translate_tags" (index (index $.Site.Data.api $apiVersion) (print "translate_tags." $.Page.Lang)) }}
{{ end }}
{{ if (fileExists (print "data/api/" $apiVersion "/translate_actions." $.Page.Lang ".json")) }}
{{ $.Scratch.Set "translate_actions" (index (index $.Site.Data.api $apiVersion) (print "translate_actions." $.Page.Lang)) }}
{{ end }}
{{ end }}
Sources: layouts/api/list.html:40-47, 131-133
Search Indexing
The search index generation is also language-aware. The layouts/_default/list.search.json template generates a JSON object for the search index. It includes the language of each page ("language": $page.Language.Lang) in the final record, allowing the search functionality to filter results by language.
Sources: layouts/_default/list.search.json:39
Automated API Documentation Generation
A significant part of the documentation, particularly for APIs, is generated automatically by Node.js scripts during the build process. These scripts are designed to handle i18n from the ground up.
The assets/scripts/build-api-pages.js and assets/scripts/build-reference-pages.js scripts contain a createTranslations function. This function extracts user-facing strings (like summaries and descriptions) from the OpenAPI specification files and writes them into intermediate JSON files (translate_tags.json, translate_actions.json) for each API version. These are the files that the Hugo templates later consume to render translated content.
The updateMenu function in the same scripts also generates language-specific menu items with correct URLs, for example: url: (language === 'en' ? '/api/latest/${tagSlug}/' : '/${language}/api/latest/${tagSlug}/' ).
This process is depicted below: