Skip to main content

Internationalization

This project maintains a separate multilingual sub-library, which includes simple multilingual processing scripts and runtime tools to meet most multilingual processing needs. The multilingual library has no third-party dependencies at runtime, allowing developers to freely choose third-party processing tools. The current web application uses react-intl-universal to handle system multilingualism.

Multilingual Library​

The multilingual library is located in the packages/locales directory, with the following structure:

locales
├── import              # Multilingual texts to be imported
│    ├── en.json        # English texts
│    └── zh.json        # Chinese texts
│
├── scripts             # Script tools
├── src                 # Application directory
│    ├── lang           # Language modules
│    ├── helper.ts      # Utility functions
│    └── index.ts       # Entry file
│
├── README.md
├── package.json
├── pnpm-lock.yaml
└── pnpm-workspace.yaml

Naming Conventions​

To avoid naming conflicts for multilingual texts, we have established a set of unified naming conventions:

  1. Text keys must be named using lowercase letters and underscores (_) in the format {level1}.{level2}.{...}.{specific_function}, with a maximum of 4 levels. For example: auth.free_trial.tip;
  2. If there are variables in the text, they must use integer placeholders, such as: "common.label.edit_title": "Edit {1}";
  3. For global texts, the key's first level should be common;
  4. For backend error code texts, the naming convention is error.http.{error_code}, where error_code is the error code returned by the backend, such as: error.http.data_no_found;

Development and Maintenance​

The multilingual library maintains the multilingual texts for all projects in the repository. To avoid loading redundant resources at runtime for each application, we use the first level of the text key as the basis for module splitting. Developers can split the file modules based on this rule, as seen in the src/lang/en directory.

While splitting modules, we also allow merging multiple first-level keys into one module. For example, in the current configuration, common, valid, and auth are merged into global.json as one module. Refer to the scripts/local.config.json configuration file for details.

Common commands:

# Import and split multilingual texts from the `import` directory
pnpm run import

# Export texts to the `.export` directory and validate them
pnpm run export

i18n Service​

The web application interface does not have an open multilingual switch entry, but the project already includes an i18n service. Developers only need to handle simple UI logic and call the i18n service to achieve multilingual switching.

The i18n service, as a general service, is maintained in the packages/shared library, involving the files shared/src/services/i18n.ts, shared/src/hooks/useI18n.ts, and shared/src/stores/global.ts. If you only need to use the i18n service in the web application, shared/src/hooks/useI18n.ts is sufficient. For custom processing, refer to shared/src/services/i18n.ts for extensions.