mdn/translated-content: how MDN Web Docs translations are contributed and reviewed

Each locale's community team decides which pull requests land

mdn/translated-content is where the non-English pages of MDN Web Docs live. It accepts contributions only to active locales, defined as locales that have community maintenance teams in place to review pull requests, fix issues, and make updates. The repository currently maintains 7 active locale groups: fr, ja, ko, pt-BR, ru, zh (covering both zh-CN and zh-TW), and es.

Each locale has its own label in the issue tracker: l10n-fr, l10n-ja, l10n-ko, l10n-pt-br, l10n-ru, l10n-zh, and l10n-es. Those labels appear in both the translated-content repository and the main mdn/content issues list, allowing contributors to find work by locale without reading every open issue.

Peer reviewers for each locale follow PEERS_GUIDELINES.md in the repository root. Contributors read CONTRIBUTING.md before submitting work; the README is short and delegates most practical detail to that file.

Markdown files in files/ carry translated pages, with front matter controlled by .front-matter-config.json

All translated pages live under files/, organized by locale code. Configuration for allowed front matter fields lives in .front-matter-config.json at the repository root. Markdown linting is split across two files: .markdownlint.jsonc holds rules and .markdownlint-cli2.jsonc holds cli2-specific settings.

Git hooks run via lefthook, configured in .lefthook.yml. Hooks enforce quality checks at commit time, so a contributor with the default setup catches formatting problems before submitting a pull request rather than after. A .nvmrc file at the repository root records the expected Node.js version.

Changes to the English source content live in a separate repository, mdn/content. Translated pages here correspond to pages in that source, and keeping a translation aligned with source updates is a recurring task for each locale's community team.

Node 24 and npm 11.8.0 are the minimum environment; the contributor workflow lives in CONTRIBUTING.md

Setting up a local contributor environment requires Node.js 24 or higher. The package.json specifies `"node": ">=24"` in the engines field, with a packageManager of [email protected] and a devEngines requirement of npm 11.8.0 or higher.

The README does not list setup commands. It says to read CONTRIBUTING.md for how to get started, so that file is the correct first stop for a new contributor rather than the README or the package.json alone. Installing dependencies with the packageManager listed in package.json is the expected first step, but the exact procedure is in CONTRIBUTING.md.

The package.json includes a prepare script that runs node scripts/npm-check.js on install. What that script checks is not described in the README.

The lint:md script chains four tools: markdownlint, URL locale check, autocorrect-node, prettier

Two npm scripts cover the Markdown editing workflow: lint:md checks files and fix:md automatically applies corrections. Running lint:md executes four tools in sequence. First, markdownlint-cli2 at version 0.23.3 checks all Markdown files against the rules in .markdownlint-cli2.jsonc. Second, the custom script scripts/check-url-locale.js scans URLs in files/ and verifies that locale-specific URLs reference the correct locale code. Third, autocorrect-node at version 2.14.0 checks spacing between CJK characters and Western text, a common formatting issue in multilingual documentation. Fourth, prettier at version 3.9.9 checks Markdown file formatting.

The fix:md counterpart runs the same four tools with fix flags instead of lint flags. markdownlint-cli2 runs with --fix, check-url-locale.js runs with --fix on the files directory, autocorrect-node runs with --fix on the whole repository, and prettier runs with -w on all Markdown files.

Because the chain uses && to connect steps, any tool failure stops execution. A partial fix run that exits mid-chain leaves some issues corrected and others unprocessed, so checking which tool stopped is necessary before assuming all problems are resolved.

A new language requires forming a community team first; locales without active teams have been closed before

A contributor who wants to add a language outside the 7 active locales cannot submit translations to this repository. Adding a new locale would require forming an active community maintenance team before the locale is opened, and the README does not describe that process beyond stating the requirement.

This policy exists because MDN has previously had more translated locales that accumulated maintenance debt: untranslated pages, outdated translations, and no reviewers to catch errors. Inactive locales became a source of incorrect or stale documentation for readers, and those locales were closed as a result.

For contributors whose language is not represented, the issue tracker on mdn/translated-content and the communication channels linked in the README are the appropriate places to raise the question.

Git-based PR workflow compared to a translation management platform

Contributing translations through pull requests differs from using a dedicated translation management system. A TMS provides a web editor aligned to source strings, machine translation suggestions, translation memory across documents, and progress tracking without requiring contributors to work with Git or local tooling.

MDN's Git-based approach means contributors work directly in Markdown files, run local tooling, and submit PRs through standard Git workflows. That puts more burden on translators to understand the repository structure and linting chain, but gives direct control over the exact output. The four-tool lint chain enforces consistency automatically rather than relying on editor conventions.

For an organization that wants to reuse MDN's linting tooling for its own documentation, the scripts here are built specifically for MDN's file structure and front matter schema. The check-url-locale.js script, the .front-matter-config.json, and the markdownlint configuration reference MDN-specific patterns and would require reworking for a different project.

Translated pages reach the MDN site through a build pipeline, not through versioned packages

Translated content reaches readers through the MDN website build pipeline; the main branch feeds directly into the MDN site rather than being distributed separately from this repository.

The license is in LICENSE.md; GitHub classifies it as Other because it does not match a standard SPDX identifier, so read it before contributing or redistributing content.

The last push to the repository was on 2026-10-06.

Editorial conclusion

Contribute to mdn/translated-content if you read MDN Web Docs in French, Japanese, Korean, Brazilian Portuguese, Russian, Simplified Chinese, Traditional Chinese, or Spanish and can commit to maintaining translated pages under PR review. Anyone hoping to add a language outside those 7 locales will find the repository closed to new locales without an active community maintenance team. Before starting, verify you have Node.js 24 or higher and npm 11.8.0 or higher; the toolchain will not run on an older Node version. Read CONTRIBUTING.md before anything else: the README points there for all first-contribution steps.

Frequently asked questions

Official sources

1. Issues
2. mdn/translated-content on GitHub
3. Project website
4. README