Skip to main content

Translating

This guide covers how to contribute translations to the Subway Builder Modded Wiki. Translators are responsible for ensuring their contributions are accurate, clear, and consistent with the original content. All contributions must follow proper grammar, maintain formatting, and be submitted via Pull Request (PR) for review.

Table of Contents​

  1. Contributing to an Existing Language
  2. Contributing a New Language
  3. MDX & i18n Guide for Translators
  4. Language-Specific Notes
  5. Important Notes
  6. Updating Translations
important

Throughout this guide, YOUR_LOCALE_CODE will refer to the language you are working on. For example, for Spanish, it would be es. For English, it would be en. For a full list, look here. For countries that have multiple regional dialects (like Chinese having zh-CN and zh-TW), you should use that as YOUR_LOCALE_CODE

Contributing to an Existing Language​

If you want to contribute translations to a language that already exists in the project:

1. Navigate to the folder corresponding to your language in i18n/YOUR_LOCALE_CODE. For example, Spanish translations are located in i18n/es.

2. You are responsible for all files in this folder, including but not limited to:

  • code.json
  • tags.yml
  • Any other .json or .yml files

3. Ensure that all text is properly translated while keeping the formatting intact (headings, lists, code blocks, notes, tips, admonitions, and images).

4. PR Requirements:

  • Any PR that anyone merges with the needs-translating tag must be translated into your language.
  • Translation PRs must begin with the prefix [Translation - YOUR_LOCALE_CODE].

5. Submit your changes via Pull Request. A wiki maintainer will review your submission before merging.

Contributing a New Language​

If you want to add a completely new language:

Step 1 - Set Up Your Locale​

1. Open docusaurus.config.js.

2. Add your language to the localeConfigs section. Example for Italian:

locales: ['en', 'es', 'fr', 'it'],
localeConfigs: {
  en: {
    label: 'English',
    htmlLang: 'en-US',
  },
  es: {
    label: 'Español',
    htmlLang: 'es-ES',
  },
  fr: {
    label: 'Français',
    htmlLang: 'fr-FR',
  },
  it: {
    label: 'Italiano',
    htmlLang: 'it-IT',
  },
},
important

If you are using a regional dialect of a language that already exists (like Chinese having zh-CN and zh-TW), you should use that instead of a 2 letter code, like fr. Example:

locales: ['en', 'es', 'zh-CN', 'zh-TW'],
localeConfigs: {
  en: {
    label: 'English',
    htmlLang: 'en-US',
  },
  es: {
    label: 'Español',
    htmlLang: 'es-ES',
  },
  zh-CN: {
    label: '中文（简体）',
    htmlLang: 'zh-CN',
  },
  zh-TW: {
    label: '中文（繁體）',
    htmlLang: 'zh-TW',
  },
},

3. Save the file.

Step 2 - Generate Translation Folders​

Run the following command to generate a new translation scaffold:

npx docusaurus write-translations --locale YOUR_LOCALE_CODE

Step 3 - Organize Your Translation Workspace​

1. Inside docusaurus-plugin-content-docs and docusaurus-plugin-content-modding-docs, create a folder called current.

2. Copy all files from docs/ and modding-docs/ into their respective current.

3. Begin translating these files. Maintain the original formatting, including:

  • Headings
  • Lists
  • Code blocks
  • Notes (:::note)
  • Tips (:::tip)
  • Important warnings (:::important)
  • Images and captions

4. Translate all other files in the directory, such as code.json and tags.yml.

5. Remember that links, page IDs, names, and image references should not be translated.

Step 4 - Submit Your PR​

  • Once all files are translated, submit a Pull Request.
  • A wiki maintainer will review your translation before it is merged.
  • Keep in mind that your contribution is responsible for everything in your language’s folder.
  • Ensure all translations are accurate, consistent, and maintain the original formatting.
  • PRs for translations must start with [Translation - YOUR_LOCALE_CODE].

MDX & i18n Guide for Translators​

Docusaurus uses i18n to manage translations, and our wiki uses MDX for enhanced formatting. Translators must understand both.

Key Responsibilities​

  • Translate all textual content in your language folder, including code.json, tags.yml, .mdx files, and any metadata.
  • Maintain all MDX formatting:
    • Page header (id and title) must remain unchanged except for translated titles.
    • Lists, headings, code blocks, and blockquotes must remain consistent.
    • Admonitions (notes, tips, important warnings):
:::note

This is a note. You may translate the text inside.

:::
  • Images and captions: do not translate filenames or captions that reference proper names.
  • Page IDs, links, and file references must not be translated.
  • Follow proper grammar and spelling for your language.
  • All headings should be static. This means if you want to have ### Responsibilities, it should instead be ### Responsibilities {#responsibilities} (case sensitive). The actual heading names should be translated. The static anchors should not.

MDX Example​

---
id: example-page
title: Example Page
---

## Heading \{#heading}

Text content here.

:::tip

This is a tip for the user.

:::
  • All text inside MDX content can be translated, including admonitions, lists, and paragraphs.
  • Do not translate anything inside code blocks, filenames, links, or IDs.
  • All city and country names should be translated to match their variant in the language.

Language-Specific Notes​

Here are details for the currently supported languages:

  • Spanish (es-ES)

    • Use standard European Spanish spelling and grammar.
    • Avoid mixing Latin American expressions.
    • Ensure accents and special characters (ñ, á, é, í, ó, ú) are correct.

  • Catalan (ca-ES)

    • Use standard Catalan spelling and grammar.
    • Maintain proper accents and diacritics (à, ç, é, è, í, ï, ó, ò, ú, ü).
    • Avoid mixing Spanish expressions; keep phrasing natural for Catalan readers.

  • French (fr-FR)

    • Use formal French; avoid overly casual phrasing.
    • Pay attention to gendered words and agreement.

  • German (de-DE)

    • Use standard High German (Hochdeutsch).
    • Maintain capitalization of nouns.
    • Compound words must be properly connected.

  • Italian (it-IT)

    • Use standard Italian spelling.
    • Maintain proper use of accents.
    • Use formal tone consistently.

  • Danish (da-DK)

    • Use standard Danish grammar and spelling.
    • Be careful with special characters (æ, ø, å).

  • Swedish (sv-SE)

    • Use standard Swedish; watch out for compound words.
    • Maintain proper accents and letters (å, ä, ö).

  • Norwegian (nb-NO)

    • Use Bokmål (not Nynorsk) unless otherwise specified.
    • Keep special characters correct (æ, ø, å).

  • Mandarin (zh-CN)

    • Use Simplified Chinese.
    • Ensure punctuation matches Mainland Chinese conventions.

  • Traditional Chinese (zh-TW)

    • Use Traditional Chinese characters.
    • Follow Taiwanese terminology and conventions where applicable.
    • Ensure punctuation follows Traditional Chinese standards.

Important Notes​

  • Pull Requests Required: All translations must be submitted via PR and reviewed by a wiki maintainer.
  • PR Naming: Translation PRs must start with [Translation - YOUR_LOCALE_CODE].
  • Needs-Translating Tag: Any PR merged with the needs-translating tag needs translating by contributors.
  • Formatting Matters: Maintain code blocks, notes, headings, lists, and image references exactly as in the original files.

Updating Translations​

1. Pull the latest changes from the main branch.

2. Review any new or updated files in docs/ and modding-docs/.

3. Translate any new content in your language folder.

4. Submit updates via PR using the [Translation - YOUR_LOCALE_CODE] prefix.

5. Repeat the review process with a wiki maintainer before merging.