Localization

Capabilities

@nocobase/app-plugin-i18n provides runtime language switching and server preference synchronization. The framework owns translation resources, namespaces and translation itself.

The plugin provides switching and synchronization; the application owns resources and picker presentation.

Scenarios and examples

Example: English and Chinese

Provide en-US and zh-CN resources on both runtimes.
Integrate a picker or reuse the template's implementation.
Switch and check pages, plugin content and server errors.
Reload to verify persistence; use useSyncServerLocale() for startup reconciliation.

Endpoints are GET /api/i18n/locales and PUT /api/i18n/locale. An unsupported server language falls back to en-US with fallback: true, while the browser keeps its choice. Transport failures also do not undo the browser selection.

Development prompt (for a Coding Agent working in the application directory):

Use Localization to add English/Chinese switching. Check client and server
resource loaders, reuse useAppLocale and existing template controls, and handle
pending and failed changes. Persist browser selection and synchronize the server
on startup. Test reloads, unsupported server languages, transport failure and
multiple tabs. Do not add automatic business-content translation.

Done whenApplication and plugin text switch, reloads retain selection, and server fallback or transport failure is handled.

Key principles and implementation

These are the integration areas and expected interface changes for this example. They describe development work; use the actual file layout of your application.

Integration area	Code or configuration change	UI and behavior change
Client and server locales	Add resources and loaders	Available languages reflect application resources
Header language picker	Use useAppLocale and handle switching/errors	Update application and plugin text
Startup synchronization and error UI	Use useSyncServerLocale and stable reasons	Synchronize server preferences with understandable fallbacks

Language sources

Register Client and Server. Available languages come from loaders declared in the application's client/locales/index.ts and server/locales/index.ts.

Add application resources and loaders to enable a language. A plugin's translations do not independently add languages to the picker.

i18n:
  defaultLocale: zh-CN

APP_DEFAULT_LOCALE overrides the default. A default without application resources does not introduce a new option.

Build a picker

Inside AppClientRoot, use:

import { useAppLocale } from '@nocobase/app-plugin-i18n/client';

const { locale, locales, setLocale, switching } = useAppLocale();

This fragment runs inside a component. Render locales, call setLocale(next), disable repeated changes while switching, and handle rejection.

Switching loads namespace resources, updates interface and HTML language/direction, saves the browser preference and synchronizes the server. Plugins share the runtime and follow the change.

AI development constraints and verification

Plugin-specific development constraints

Derive choices from application loaders, not a separate hard-coded list.
Handle setLocale failures; server fallback does not mean the browser selection was undone.
Check missing text, reload persistence, shared-session tabs and server errors; type checks do not establish locale coverage.

Boundaries

Tabs sharing a session share its server locale, so another tab's requests may change language before its interface does. Render localized errors from stable error.reason values when needed.

This plugin does not automatically translate business content or provide a translation administration UI. See Client localization and Server localization.

These are acceptance requirements for your integration, not claims of completed live verification. Ask the Agent to report actual changes, executed checks and unverified items. See Continue developing your app and Testing for project guidance, Skills and shared checks.

Source: public plugin entries and implementation.