Translations

Translations#

Warning

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

Extensions 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 extension project:

nextgen 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 extension namespace.

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

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: ExtensionManifest = {
  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 extension:

{
  "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 nextgen translations init exports a pre-bound hook pointing to your extension 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 nextgen 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.

Those four files correspond to the four languages the Project Neo interface supports. The language selector offers only English, German, French, and Italian. Adding a translation file for any other locale has no effect at runtime: i18next only resolves keys for the four supported languages, so a fifth file would never be used.

Note

If an engagement requires a language outside this list, that requires a change to the host platform and is outside the scope of extension development.

How It Works#

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

  • Keys without a colon are added under the ext-{extensionName} 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