Translations

Translations#

Warning

Project Neo is currently in Technical Preview. Features described in this section may change before general availability.

Bundles can provide localized strings and override host UI text. No host code changes are required. The CLI scaffolds everything you need.

Setup#

Run this command once in your bundle:

neo-ui translations init

Running the command creates the following files:

  • src/translations/en.json, de.json, fr.json, and it.json

    Translation files for each supported language.

  • src/translations/use-translation.ts

    A typed useExtTranslation() hook pre-bound to your bundle namespace.

It also updates src/manifest.ts to import and pass the translation files. After running the command, the manifest includes:

import en from './translations/en.json' with { type: 'json' };
import de from './translations/de.json' with { type: 'json' };
import fr from './translations/fr.json' with { type: 'json' };
import it from './translations/it.json' with { type: 'json' };

const manifest: BundleManifest = {
  name: 'my-dashboards',
  dashboards: [...],
  translations: { en, de, fr, it },
};

Note

This command fails if translations are already configured in the project.

Your Own Strings#

Keys without a colon go into the ext-{name} namespace. Use them for strings that belong to your bundle:

{
  "dashboard.title": "Analytics",
  "dashboard.empty": "No data available for this period"
}

In your component:

import { useExtTranslation } from '../translations/use-translation';

function Analytics() {
  const { t } = useExtTranslation();
  return <h1>{t('dashboard.title')}</h1>;
}

The use-translation.ts file created by neo-ui translations init exports a pre-bound hook pointing to your bundle namespace.

Overriding Host Strings#

Keys with a colon (namespace:key) override the matching key in the host application. Use this to customize host UI text:

{
  "chat:welcome.inputPlaceholder": "Search legislation and case law..."
}

Discovering Keys to Override#

There are two ways to find the key behind any piece of text in the host UI.

Option 1: Dev Translate Keys#

When running neo-ui dev, the host language selector (in the bottom-left corner) shows an extra option: Dev: Translate Keys. Selecting it replaces all visible text in the UI with its namespace:key identifier. Copy any key directly from the UI and add it to your translation JSON file. Switch back to a supported language to restore normal text.

Adding Translations to Your Own Dashboards#

Provide translations for all supported languages by editing each JSON file in src/translations/:

File

Language

en.json

English

de.json

German

fr.json

French

it.json

Italian

Keys must be identical across all files. Missing keys fall back to English.

Adding More Languages#

The four built-in languages (English, German, French, and Italian) are always present and cannot be re-added. To support a language beyond the four built-ins, run neo-ui translations add-locale:

neo-ui translations add-locale es

That command prompts for a display name. To provide the display name directly, pass the --label option:

neo-ui translations add-locale pt-BR --label "Português (Brasil)"

The command copies en.json to src/translations/<code>.json as your starting point and wires the locale into src/manifest.ts (the import, the translations object, and a localeLabels entry that sets the name shown in the host language selector). Then translate the strings in the new JSON file.

How It Works#

When the host loads your bundle manifest, it reads the translations field and registers the strings with the shared i18next instance:

  • Keys without a colon are added under the ext-{bundleName} namespace, isolated from host keys.

  • Keys with a colon (for example, chat:welcome.title) are merged into the matching host namespace, overriding the host value for that key.

That registration happens at load time. No additional setup is needed in your dashboard components beyond using the useExtTranslation() hook for your own strings.


Contents