Skip to main content
Translation of the Node.js website is managed through Crowdin. The workflow is largely automated via GitHub Actions.

​
How Translations Sync

1

Content is authored in English

All new content is created in apps/site/pages/en/. UI strings are added to packages/i18n/locales/en.json.
2

Push to main uploads source content

On every push to the main branch, a GitHub Actions workflow uploads any new English source content to Crowdin. This notifies translators that new strings are available.
3

Translators work in Crowdin

Community translators join the Crowdin project and translate strings using the Crowdin online editor.
4

Cron job downloads completed translations

On a scheduled cron, and manually when triggered by a collaborator, a GitHub Actions workflow downloads completed translations from Crowdin into the repository.
5

Translations are linted and formatted

Incoming translations are linted to confirm they originate from Crowdin and are formatted to match project settings before being committed.

​
How to Contribute Translations

  1. Request to join the project at crowdin.com/project/nodejs-web
  2. Select the language you want to translate
  3. Use the Crowdin online editor to translate strings
For questions or feedback on existing translations, start a Crowdin discussion or open a conversation with other translators.

​
Adding Translation Keys

When building a new component that needs translated strings:
1

Add keys to en.json only

Add new keys to packages/i18n/locales/en.json. Do not add them to other locale files — Crowdin handles syncing.
2

Place keys at the bottom

New keys should be appended to the bottom of en.json so translators can easily spot that new strings need attention.
3

Follow the naming convention

Keys are nested JSON matching the component’s canonical path. For a component at components/Common/MyComponent:
{
  "components": {
    "common": {
      "myComponent": {
        "copyButton": {
          "title": "Copy to clipboard"
        }
      }
    }
  }
}
4

Use full key paths in components

Always reference the full key path when calling useTranslations():
// Correct
const t = useTranslations();
t('components.common.myComponent.copyButton.title');

// Incorrect — partial prefix breaks static analysis
const t = useTranslations('components.common.myComponent');
t('copyButton.title');

​
Which Sections Are Translated

Not all sections of the website are translated. The decision depends on the nature of the content and the team’s capacity to ensure translation quality.

​
Translated Sections

Home Page

Translated because it is the first page visitors see. It is critical that everyone understands what Node.js is and what it can do.

About

Translated because it contains information about the Node.js project and its governance. The content uses relatively few technical terms.

Download

Translated because knowing how to download Node.js is essential for all users, regardless of language.

​
Sections Not Translated

Learn

Not translated per TSC consensus. The Learn section contains many technical terms that are difficult to translate accurately. Maintainers do not have the bandwidth to ensure quality, and it is considered better to have accurate English content than poor translations.

Blog

Not translated because most blog posts are release notes, and translating them would not provide meaningful value to users.

Docs (API)

The API documentation is too expansive and too frequently versioned to translate and maintain.
For more background on the Learn section decision, see this GitHub comment.

​
Testing with Translations

Unit tests should not translate strings. If a component uses useTranslations, wrap the test render with <NextIntlProvider> but do not import the real English messages file.
  • Test component behavior, not text content
  • Use aria-* attributes, class names, or other non-text selectors
  • Visual Regression Testing (via Chromatic) is the appropriate tool for verifying how different languages look in a component

Build docs developers (and LLMs) love

Get started for freeTalk to us