Internationalization (i18n) Workflow

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• CLAUDE.md
• apps/desktop/README.md
• packages/prompts/src/chains/summaryDescription.ts
• src/layout/GlobalProvider/Locale.tsx
• src/locales/resources.ts
• scripts/i18nWorkflow/index.ts
• FILE_UPLOAD_COMPREHENSIVE_ANALYSIS.md

The internationalization (i18n) system in LobeChat is designed to support multiple languages across the application, providing a localized experience for users worldwide. The system is built upon the i18next framework and features a semi-automated workflow that simplifies the process for developers. It supports both the web and desktop applications, with features like lazy-loading of language resources and dynamic UI updates.

The core of the workflow involves developers adding new translation keys to a default file. A CI/CD process then automatically handles the translation into other supported languages. This approach ensures consistency and reduces the manual translation burden on the development team.

Sources: AGENTS.md:61-64, CLAUDE.md:43-46, apps/desktop/README.md:203-207

Architecture Overview

The i18n architecture is composed of several key parts: language resource files (JSON), a resource definition module, a React provider for the frontend, and an automated script for managing translations. The desktop application extends this with its own I18nManager for deeper OS integration.

This diagram illustrates the main components of the i18n system and their interactions.

Key Components

This table summarizes the essential files involved in the i18n system.

File/Directory	Role
locales/	Directory containing all language-specific JSON translation files.
src/locales/resources.ts	Defines the structure of language resources and configures dynamic imports for each locale and namespace.
src/layout/GlobalProvider/Locale.tsx	React component that initializes i18next and wraps the application with the I18nextProvider.
scripts/i18nWorkflow/index.ts	A script that automates the translation process, including finding missing keys and generating translations.
apps/desktop/README.md	Describes the I18nManager for the desktop application, which handles lazy loading and OS locale detection.
AGENTS.md / CLAUDE.md	Development guideline documents that specify the i18n workflow for contributors.

Language Resource Management

Language resources are organized by locale and namespace. The central definition for these resources is in src/locales/resources.ts.

Resource Structure

The resources object maps each locale (e.g., en-US, zh-CN) to its available namespaces. Each namespace is dynamically imported, which allows for lazy loading of translations.

// src/locales/resources.ts:10-21
export const resources = {
  'en-US': {
    common: () => import('../../locales/en-US/common.json').then((m) => m.default),
    // ... other namespaces
  },
  'zh-CN': {
    common: () => import('../../locales/zh-CN/common.json').then((m) => m.default),
    // ... other namespaces
  },
  // ... other locales
} as const;

This structure is used to configure i18next, telling it where to find the translation files for a given language and namespace.

Sources: src/locales/resources.ts:10-21

AI-Powered Translations

The system also leverages AI to generate translations for certain dynamic content, such as summarizing an agent's capabilities. The chainSummaryDescription function constructs a prompt that instructs an AI to summarize text and translate it to a specified locale.

This demonstrates a hybrid approach where static UI text is handled by JSON files, and dynamic, content-specific text can be translated on-the-fly.

// packages/prompts/src/chains/summaryDescription.ts:5-8
export const chainSummaryDescription = (
  content: string,
  locale: string,
): Partial<ChatStreamPayload> => ({
  messages: [
    {
      content: `你是一名擅长技能总结的助理，你需要将用户的输入的内容总结为一个角色技能简介，不超过 20 个字。内容需要确保信息清晰、逻辑清晰，并有效地传达角色的技能和经验，需要并翻译为目标语言:${locale}。格式要求如下：\n输入: {文本作为JSON引用字符串} [locale]\n输出: {简介}`,
      role: 'system',
    },
// ... example prompts

Sources: packages/prompts/src/chains/summaryDescription.ts:5-8

Developer Workflow

The development guidelines outline a streamlined process for adding new translations.

1. Add Keys: A developer adds new translation keys to a default namespace file (e.g., src/locales/default/common.ts, as implied by guidelines).
2. Translate for Dev: For development preview, the developer only needs to add the translation for the zh-CN locale.
3. CI Automation: The CI pipeline runs the pnpm i18n command, which executes the i18nWorkflow script. This script automatically translates the new keys into all other supported languages.
4. Manual Execution Forbidden: Developers are explicitly instructed not to run pnpm i18n manually.

This workflow minimizes developer effort and ensures that all languages are kept in sync automatically.

Sources: AGENTS.md:61-64, CLAUDE.md:43-46

Automated Translation Script

The i18nWorkflow/index.ts script is the engine behind the automated translation process. It performs several actions, including checking for untranslated keys, translating them, and creating new locale files if needed.

The following flowchart shows the logic of the i18nWorkflow script.

This script is crucial for maintaining consistency across the 18+ languages supported by the application.

Sources: scripts/i18nWorkflow/index.ts, apps/desktop/README.md:204

Application Integration

React Web Application

In the main web application, i18n is managed by the Locale component within the GlobalProvider. This component is responsible for:

• Initializing i18next with the defined resources.
• Detecting the user's preferred language from settings or the browser.
• Wrapping the entire application in an I18nextProvider to make translation functions available to all components.

The following sequence diagram shows how a component receives and displays a translated string.

Desktop Application

The desktop application features a dedicated I18nManager to handle its specific needs. This manager provides:

• Support for over 18 languages with lazy loading to optimize performance.
• Integration with Electron's app.getLocale() for automatic language detection based on the user's OS settings.
• Dynamic UI refresh when the language is changed.
• Organization of resources into namespaces.

This ensures a seamless and native-feeling experience for desktop users.

Sources: apps/desktop/README.md:203-207

Conclusion

LobeChat's internationalization workflow is a robust and developer-friendly system that effectively combines manual key definition with automated AI-powered translation. By leveraging i18next and custom scripts, the project supports a wide range of languages with minimal overhead. The clear separation of concerns—from resource definition and application integration to the automated CI pipeline—ensures that the application can be easily localized and maintained, providing a global user base with a high-quality, native experience.

Sources: AGENTS.md:61-64, scripts/i18nWorkflow/index.ts, src/layout/GlobalProvider/Locale.tsx