docs/docs/en/get-started/translations.md
The default language of NocoBase is English. Currently, the main application supports English, Italian, Dutch, Simplified Chinese, and Japanese. We sincerely invite you to contribute translations for additional languages, enabling users around the world to enjoy an even more convenient NocoBase experience.
This applies only to the localization of the NocoBase system interface and plugins, and does not cover other custom content (such as data tables or Markdown blocks).
NocoBase uses Git to manage its localization content. The primary repository is: https://github.com/nocobase/nocobase/tree/main/locales
Each language is represented by a JSON file named according to its language code (e.g., de-DE.json, fr-FR.json). The file structure is organized by plugin modules, using key-value pairs to store translations. For example:
{
// Client plugin
"@nocobase/client": {
"(Fields only)": "(Fields only)",
"12 hour": "12 hour",
"24 hour": "24 hour"
// ...other key-value pairs
},
"@nocobase/plugin-acl": {
// Key-value pairs for this plugin
}
// ...other plugin modules
}
When translating, please gradually convert it to a structure similar to the following:
{
// Client plugin
"@nocobase/client": {
"(Fields only)": "(Fields only - translated)",
"12 hour": "12 hour - translated",
"24 hour": "24 hour - translated"
// ...other key-value pairs
},
"@nocobase/plugin-acl": {
// Key-value pairs for this plugin
}
// ...other plugin modules
}
After completing your translation, please test and verify that all texts display correctly.
We've also released a translation validation plugin - search for Locale tester in the plugin marketplace.
After installation, copy the JSON content from the corresponding localization file in the git repository, paste it inside, and click OK to verify if the translation content is effective.
Once submitted, system scripts will automatically synchronize the localization content to the code repository.
<!-- TODO: Add details about 2.0 localization plugin differences -->Note: This section is under development. The localization plugin for NocoBase 2.0 has some differences from the 1.x version. Details will be provided in a future update.
The documentation for NocoBase 2.0 is managed in a new structure. The documentation source files are located in the main NocoBase repository:
https://github.com/nocobase/nocobase/tree/next/docs
The documentation uses Rspress as the static site generator and supports 8 languages. The structure is organized as follows:
docs/
├── docs/
│ ├── en/ # English (source language)
│ ├── cn/ # Simplified Chinese
│ ├── ja/ # Japanese
│ ├── de/ # German
│ ├── fr/ # French
│ ├── es/ # Spanish
│ ├── pt/ # Portuguese
│ ├── ru/ # Russian
│ └── public/ # Shared assets (images, etc.)
├── theme/ # Custom theme
├── rspress.config.ts # Rspress configuration
└── package.json
Sync with English source: All translations should be based on the English documentation (docs/en/). When the English documentation is updated, translations should be updated accordingly.
Branch strategy:
develop or next branch as the reference for the latest English contentFile structure: Each language directory should mirror the English directory structure. For example:
docs/en/get-started/index.md → docs/ja/get-started/index.md
docs/en/api/acl/acl.md → docs/ja/api/acl/acl.md
develop or next branchdocs/docs/ directoryja/ for Japanese)cd docs
yarn install
yarn dev
docs/public/ - images are shared across all languagesThe navigation structure for each language is defined in _nav.json and _meta.json files within each language directory. When adding new pages or sections, make sure to update these configuration files.
The website pages and all content are stored in: https://github.com/nocobase/website
When adding a new language, please refer to the existing language pages:
Global style modifications are located at:
The website's global component localization is available at: https://github.com/nocobase/website/tree/main/src/components
We use a mixed content management approach. English, Chinese, and Japanese content and resources are regularly synchronized from the CMS system and overwritten, while other languages can be edited directly in local files. Local content is stored in the content directory, organized as follows:
/content
/articles # Blog articles
/article-slug
index.md # English content (default)
index.cn.md # Chinese content
index.ja.md # Japanese content
metadata.json # Metadata and other localization properties
/tutorials # Tutorials
/releases # Release information
/pages # Some static pages
/categories # Category information
/article-categories.json # Article category list
/category-slug # Individual category details
/category.json
/tags # Tag information
/article-tags.json # Article tag list
/release-tags.json # Release tag list
/tag-slug # Individual tag details
/tag.json
/help-center # Help center content
/help-center-tree.json # Help center navigation structure
....
index.md to index.fr.md){
"id": 123,
"title": "English Title", // English title (default)
"title_cn": "中文标题", // Chinese title
"title_ja": "日本語タイトル", // Japanese title
"description": "English description",
"description_cn": "中文描述",
"description_ja": "日本語の説明",
"slug": "article-slug", // URL path (usually not translated)
"status": "published",
"publishedAt": "2025-03-19T12:00:00Z"
}
Translation Notes:
Field Naming Convention: Translation fields typically use the {original_field}_{language_code} format
When Adding a New Language:
CMS Synchronization Mechanism:
To add support for a new language, you need to modify the SUPPORTED_LANGUAGES configuration in the src/utils/index.ts file:
export const SUPPORTED_LANGUAGES = {
en: {
code: 'en',
locale: 'en-US',
name: 'English',
default: true
},
cn: {
code: 'cn',
locale: 'zh-CN',
name: 'Chinese'
},
ja: {
code: 'ja',
locale: 'ja-JP',
name: 'Japanese'
},
// Example of adding a new language:
fr: {
code: 'fr',
locale: 'fr-FR',
name: 'French'
}
};
Each language needs corresponding layout files:
src/layouts/BaseFR.astro)BaseEN.astro) and translate itCreate independent page directories for the new language:
src directory (e.g., src/fr/)src/en/).layout: '@/layouts/BaseFR.astro')Some common components also need translation:
src/components/ directory{Astro.url.pathname.startsWith('/en') && <p>English content</p>}
{Astro.url.pathname.startsWith('/cn') && <p>中文内容</p>}
{Astro.url.pathname.startsWith('/fr') && <p>Contenu français</p>}
After completing the translation, conduct thorough testing:
yarn dev)If you want to contribute a new language translation to NocoBase, please follow these steps:
| Component | Repository | Branch | Notes |
|---|---|---|---|
| System Interface | https://github.com/nocobase/nocobase/tree/main/locales | main | JSON locale files |
| Documentation (2.0) | https://github.com/nocobase/nocobase | develop / next | docs/docs/<lang>/ directory |
| Website | https://github.com/nocobase/website | main | See Section III |
After completing your translation, please submit a Pull Request to NocoBase. The new languages will appear in the system configuration, allowing you to select which languages to display.
For NocoBase 1.x translation guide, please refer to: