How to carry out multilingual translation work ？

[K1vinL]

How to carry out multilingual translation work ？
From the Localization notes and tips,I didn't find any instructions on how to start with the localization work for the doc repository.

[CybCom]

So is there any localization work for the doc repository? Should we start it?

[offhub]

Multilingual Translation Contribution Guide

How to Contribute Translations

1. Fork the Repository

   • Create your own copy by forking the main repository to your GitHub account

2. Translate the Content

   • Localize these English source files:
     • docs/Content/ (all .md files)
     • docs/PlusContent/ (all .md files)
     • docs/README.md (root readme file)
   • Save translations in corresponding locale folders:
     • Example: docs/xx/Content/ (replace "xx" with your locale code)

3. Add Localized Screenshots (If Needed)

   • Capture screenshots directly from the application UI with your target locale selected
   • Store them in the appropriate locale's Media folder (e.g., docs/xx/Media/)
   • Maintain original image dimensions and quality

4. Submit Your Changes

   • Push all changes to your forked repository
   • Open a Pull Request (PR) to the main repository's primary branch
   • Include a clear description of your translation work in the PR

Correct Repository Structure

📁 docs
│
├── 📁 Content          - English source documentation
├── 📁 Media            - English source screenshots/assets
├── 📁 PlusContent      - Additional English content
├── 📄 README.md        - English root readme
│
├── 📁 tr               - Turkish translations
│   ├── 📁 Content
│   ├── 📁 Media
│   ├── 📁 PlusContent
│   └── 📄 README.md
│
├── 📁 de               - German translations
│   ├── 📁 Content
│   ├── 📁 Media
│   ├── 📁 PlusContent
│   └── 📄 README.md
│
[...all other locale folders...]
│
└── 📁 zh-CN            - Chinese Simplified translations
    ├── 📁 Content
    ├── 📁 Media
    ├── 📁 PlusContent
    └── 📄 README.md

Supported Locales: ¹

Arabic (ar), Chinese Simplified (zh -> zh-CN), Chinese Traditional (zh-TW)

Dutch (nl), English (en), French (fr), German (de)

Hungarian (hu), Indonesian (id), Italian (it), Japanese (ja)

Korean (ko), Polish (pl), Portuguese (pt), Brazilian Portuguese (pt-BR)

Russian (ru), Spanish (es), Swedish (sv), Turkish (tr)

Ukrainian (uk), Vietnamese (vi)

Key Notes:

• English source files are at the root of docs/ (not in an "en" folder)
• Each translation locale has its own folder with identical subfolder structure
• Always maintain the same directory structure in translations as the English source
• Always maintain exact source filenames (e.g., AllPages.md stays AllPages.md)
• Replace "xx" in paths with your actual two-letter locale code (e.g., "tr" for Turkish)

Strict Link Handling Rules:

1. Never modify external links

   • Keep all URLs, documentation references, and hyperlinks exactly as they appear in the English source. Only translate surrounding text.
   • Example:

     [Visit Sandboxie Plus](https://sandboxie-plus.com/)  # URL remains unchanged

2. Preserve internal links (they usually work as-is)

   • Internal links (e.g., [Link Text](../Content/File.md)) are relative paths and typically don't need adjustment since the folder structure mirrors the source.
   • Only modify if:
     • The linked file was moved to a different location in your translation
     • The link points to an anchor (#section) that was renamed in your translation
   • Always verify the link works after any changes.

3. Do NOT add or remove links without permission

   • Never introduce new hyperlinks or delete existing ones without explicit approval
   • Report broken/outdated links via issues instead of modifying them directly

Footnotes

1. https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/?h=lang#site-language ↩