Internationalization
Overview
The Backstage core function provides internationalization for plugins and apps. The underlying library is i18next with some additional Backstage typescript magic for type safety with keys.
For a plugin developer
When you are creating your plugin, you have the possibility to use createTranslationRef to define all messages for your plugin. For example:
import { createTranslationRef } from '@backstage/frontend-plugin-api';
/** @alpha */
export const myPluginTranslationRef = createTranslationRef({
id: 'plugin.my-plugin',
messages: {
indexPage: {
title: 'All your components',
createButtonTitle: 'Create new component',
},
entityPage: {
notFound: 'Entity not found',
},
},
});
And then use these messages in your components like:
import { useTranslationRef } from '@backstage/frontend-plugin-api';
const { t } = useTranslationRef(myPluginTranslationRef);
return (
<PageHeader title={t('indexPage.title')}>
<Button onClick={handleCreateComponent}>
{t('indexPage.createButtonTitle')}
</Button>
</PageHeader>
);
You will see how the initial dictionary structure and nesting get converted into dot notation, so we encourage camelCase in key names and lean on the nesting structure to separate keys.
Guidelines for i18n messages and keys
The API for i18n messages and keys can be pretty tricky to get right, as it's a pretty flexible API. We've put together some guidelines to help you get started that encourage good practices when thinking about translating plugins:
Key names
When defining messages it is recommended to use a nested structure that represents the semantic hierarchy in your translations. This allows for better organization and understanding of the structure. For example:
export const myPluginTranslationRef = createTranslationRef({
id: 'plugin.my-plugin',
messages: {
dashboardPage: {
title: 'All your components',
subtitle: 'Create new component',
widgets: {
weather: {
title: 'Weather',
description: 'Shows the weather',
},
calendar: {
title: 'Calendar',
description: 'Shows the calendar',
},
},
},
entityPage: {
notFound: 'Entity not found',
},
},
});
Think about the semantic placement of content rather than the text content itself. Group related translations under a common prefix, and use nesting to represent relationships between different parts of your application. It's good to start grouping under extensions, page sections, or visual scopes and experiences.
Translations should avoid using their own text content as key where possible, as this can lead to confusion if the translation changes. Instead prefer to use keys that describe the location or usage of the text.
Common Key names
This list is intended to grow over time, but below are some examples of common key names and patterns that we encourage you to use where possible:
-
${page}.title -
${page}.subtitle -
${page}.description -
${page}.header.title
Key reuse
Reusing the same key in multiple places is discouraged. This helps prevent ambiguity, and instead keeps the usage of each key as clear as possible. Consider creating duplicate keys that are grouped under a semantic section instead.
Flat keys
Avoid a flat key structure at the root level, as it can lead to naming conflicts and make the translation file harder to manage and change evolve over time. Instead, group translations under a common prefix.
export const myPluginTranslationRef = createTranslationRef({
id: 'plugin.my-plugin',
messages: {
// this is BAD
title: 'My page',
subtitle: 'My subtitle',
// this is GOOD
dashboardPage: {
header: {
title: 'All your components',
subtitle: 'Create new component',
},
},
},
});
Plurals
The i18next library, which is used as the underlying implementation, has built-in support for pluralization. You can use this feature as is described in the documentation.
We encourage you to use this feature and avoid creating different key prefixes for pluralized content. For example:
export const myPluginTranslationRef = createTranslationRef({
id: 'plugin.my-plugin',
messages: {
dashboardPage: {
title: 'All your components',
subtitle: 'Create new component',
cards: {
title_one: 'You have one card',
title_two: 'You have two cards',
title_other: 'You have many cards ({{count}})',
},
},
entityPage: {
notFound: 'Entity not found',
},
},
});
JSX Elements
The translation API supports interpolation of JSX elements by passing them directly as values to the translation function. If any of the provided interpolation values are JSX elements, the translation function will return a JSX element instead of a string.
For example, you might define the following messages:
export const myPluginTranslationRef = createTranslationRef({
id: 'plugin.my-plugin',
messages: {
entityPage: {
redirect: {
message: 'The entity you are looking for has been moved to {{link}}.',
link: 'new location',
},
},
},
});
Which can be used within a component like this:
const { t } = useTranslationRef(myPluginTranslationRef);
return (
<div>
{t('entityPage.redirect.message', {
link: <a href="/new-location">{t('entityPage.redirect.link')}</a>,
})}
</div>
);
The return type of the outer t function will be a JSX.Element, with the underlying value being a React fragment of the different parts of the message.
For an application developer
As an app developer you can both override the default English messages of any plugin, and provide translations for additional languages.
Overriding messages
To customize specific messages without adding new languages, create a translation extension using TranslationBlueprint from @backstage/plugin-app-react together with createTranslationMessages from @backstage/frontend-plugin-api:
import { createTranslationMessages } from '@backstage/frontend-plugin-api';
import { TranslationBlueprint } from '@backstage/plugin-app-react';
import { catalogTranslationRef } from '@backstage/plugin-catalog/alpha';
const catalogTranslations = TranslationBlueprint.make({
name: 'catalog-overrides',
params: {
resource: createTranslationMessages({
ref: catalogTranslationRef,
messages: {
'indexPage.title': 'Service directory',
'indexPage.createButtonTitle': 'Register new service',
},
}),
},
});
Register the extension in an app module, then add the module to your app's existing features:
import { createApp } from '@backstage/frontend-defaults';
import { createFrontendModule } from '@backstage/frontend-plugin-api';
const appModuleTranslations = createFrontendModule({
pluginId: 'app',
extensions: [catalogTranslations],
});
const app = createApp({
features: [
// ...your existing features
appModuleTranslations,
],
});
The examples in this guide define modules inline for simplicity. You can also place a frontend module in a separate package in your workspace.
You only need to include the keys you want to override — any missing keys fall back to the plugin's defaults.
Adding language translations
To add support for additional languages, create a translation resource with lazy-loaded message files for each language, and install it using TranslationBlueprint:
import { createTranslationResource } from '@backstage/frontend-plugin-api';
import { TranslationBlueprint } from '@backstage/plugin-app-react';
import { userSettingsTranslationRef } from '@backstage/plugin-user-settings/alpha';
const userSettingsTranslations = TranslationBlueprint.make({
name: 'user-settings-zh',
params: {
resource: createTranslationResource({
ref: userSettingsTranslationRef,
translations: {
zh: () => import('./userSettings-zh'),
},
}),
},
});
The translation messages can be defined using createTranslationMessages for type safety:
// packages/app/src/translations/userSettings-zh.ts
import { createTranslationMessages } from '@backstage/frontend-plugin-api';
import { userSettingsTranslationRef } from '@backstage/plugin-user-settings/alpha';
const zh = createTranslationMessages({
ref: userSettingsTranslationRef,
full: false, // False means that this is a partial translation
messages: {
'languageToggle.title': '语言',
'languageToggle.select': '选择{{language}}',
},
});
export default zh;
Or as a plain object export:
// packages/app/src/translations/userSettings-zh.ts
export default {
'languageToggle.title': '语言',
'languageToggle.select': '选择{{language}}',
'languageToggle.description': '切换语言',
'themeToggle.title': '主题',
'themeToggle.description': '切换主题',
'themeToggle.select': '选择{{theme}}',
'themeToggle.selectAuto': '选择自动主题',
'themeToggle.names.auto': '自动',
'themeToggle.names.dark': '暗黑',
'themeToggle.names.light': '明亮',
};
Register the translation extension in an app module. If you already have an app module for translations, add it to that module's extensions array instead:
import { createApp } from '@backstage/frontend-defaults';
import { createFrontendModule } from '@backstage/frontend-plugin-api';
const appModuleTranslations = createFrontendModule({
pluginId: 'app',
extensions: [userSettingsTranslations],
});
const app = createApp({
features: [
// ...your existing features
appModuleTranslations,
],
});
Declaring available languages
Installing translation extensions makes the translated messages available, but the language switcher in the Settings page only appears once you declare two or more supported languages. Configure this in your app-config.yaml using the api:app/app-language extension:
app:
extensions:
- api:app/app-language:
config:
availableLanguages:
- en
- zh
defaultLanguage: en
The availableLanguages array controls which languages appear as options in the Settings page. The defaultLanguage sets the language used before the user makes a selection, and defaults to en if not specified. If you configure availableLanguages, the defaultLanguage must be one of those entries — if you omit defaultLanguage, make sure en is included in availableLanguages, otherwise the app can fail to start.
Go to the Settings page — you should see a language select dropdown. Switch languages to verify your translations are loaded correctly.
Translating page titles
Page and sub-page blueprints accept either a plain title string or a message reference. To enable a translated title, select a message from your plugin's existing translation ref:
PageBlueprint.make({
params: {
path: '/my-plugin',
title: myPluginTranslationRef('indexPage.title'),
loader: () => import('./MyPage').then(m => <m.MyPage />),
},
});
SubPageBlueprint accepts the same title form for its tab and breadcrumb label.
EntityContentBlueprint from @backstage/plugin-catalog-react/alpha also accepts
message references for entity content titles:
EntityContentBlueprint.make({
name: 'overview',
params: {
path: '/overview',
title: myPluginTranslationRef('entityPage.overview'),
loader: () => import('./EntityOverview').then(m => <m.EntityOverview />),
},
});
Both catalog entity page layouts update tab labels, grouped tab ordering, and the active content's document title when the language changes, preserving mounted content and form state.
Install translations using the existing TranslationBlueprint and translation
resources described above. No additional title bundles or APIs are required.
Existing string title parameters keep their behavior.
Translated title groups wait until their selected-language resources are ready before first rendering, showing the app's loading indicator in the meantime. Their resolved values take precedence over configured and plain titles, including when the translation API resolves to a default-language message for a missing translation. Existing language fallbacks remain unchanged. During later language changes, each group updates together once all of its translation resources are ready. Until then, the previous resolved titles remain visible without remounting page content. Hidden entity tabs and pages excluded from navigation do not delay the corresponding visible titles.
If a title resource fails to load, previously resolved titles remain visible. A group without resolved titles uses the translation API's available fallback messages instead. Failures are reported without replacing the page or navigation with an error screen. Selecting another language resumes normal loading.
When an entity refresh changes the available tabs, existing visible tabs keep their resolved titles and form state. Newly visible translated tabs wait until the replacement title group is ready. Opening a pending tab directly shows the loading indicator until that group is ready.
TypeScript checks the selected key and rejects title messages that require replacement values or a plural count. Nested messages are supported when none of the referenced messages require values.
Consuming title translations
Extensions can provide coreExtensionData.titleTranslation alongside their static
title. It contains a TranslationRefTuple<undefined> with a ref and key,
selecting a message that needs no formatting values.
To render the translated title in React, pass the ref to useTranslationRef and
translate the selected key. The hook uses the app translation API and waits for
the selected language's resources:
import {
TranslationRefTuple,
useTranslationRef,
} from '@backstage/frontend-plugin-api';
function TranslatedTitle({ title }: { title: TranslationRefTuple<undefined> }) {
const { t } = useTranslationRef(title.ref);
return <>{t(title.key)}</>;
}
Using the CLI for full translation workflows
When translating your app to other languages at scale — especially when working with external translation systems — the Backstage CLI provides translations export and translations import commands that automate the extraction and wiring of translation messages across all your plugin dependencies.
Exporting default messages
From your app package directory (e.g. packages/app), run:
yarn backstage-cli translations export
This scans all frontend plugin dependencies (including transitive ones) for TranslationRef definitions and writes their default English messages as JSON files:
translations/
manifest.json
messages/
catalog.en.json
org.en.json
scaffolder.en.json
...
Each .en.json file contains the flattened message keys and their default values:
{
"indexPage.title": "All your components",
"indexPage.createButtonTitle": "Create new component",
"entityPage.notFound": "Entity not found"
}
Creating translations
Copy the exported files and translate them for your target languages:
cp translations/messages/catalog.en.json translations/messages/catalog.zh.json
Then edit catalog.zh.json with the translated strings. You only need to include the keys you want to translate — missing keys fall back to the English defaults at runtime.
Generating wiring code
Once you have translated files in place, run:
yarn backstage-cli translations import
This generates a TypeScript module at src/translations/resources.ts that exports an array of translation resources with lazy-loaded message files:
// This file is auto-generated by backstage-cli translations import
// Do not edit manually.
import { createTranslationResource } from '@backstage/frontend-plugin-api';
import { catalogTranslationRef } from '@backstage/plugin-catalog/alpha';
export default [
createTranslationResource({
ref: catalogTranslationRef,
translations: {
zh: () => import('../../translations/messages/catalog.zh.json'),
},
}),
];
Create a TranslationBlueprint extension for each resource and register the extensions in a module for the app plugin. Use each resource's id as its extension name so the names are unique within the module:
import { createApp } from '@backstage/frontend-defaults';
import { createFrontendModule } from '@backstage/frontend-plugin-api';
import { TranslationBlueprint } from '@backstage/plugin-app-react';
import translationResources from './translations/resources';
const appModuleTranslations = createFrontendModule({
pluginId: 'app',
extensions: translationResources.map(resource =>
TranslationBlueprint.make({
name: resource.id,
params: { resource },
}),
),
});
const app = createApp({
features: [
// ...your existing features
appModuleTranslations,
],
});
Keep this registration outside the generated file so it is preserved when you rerun translations import.
To make the imported languages selectable, also declare the available languages.
Custom file patterns
By default, message files use the pattern messages/{id}.{lang}.json (e.g. messages/catalog.en.json). You can change this with the --pattern option:
yarn backstage-cli translations export --pattern '{lang}/{id}.json'
This produces a directory structure grouped by language instead:
translations/en/catalog.json
translations/zh/catalog.json
The pattern is stored in the manifest, so the import command automatically uses the same layout.
Integration with external translation systems
The exported JSON files are standard key-value pairs compatible with most external translation systems. A typical workflow looks like:
- Run
translations exportto generate the source English files - Upload the
.en.jsonfiles to your translation system - Download the translated files back into the translations directory
- Run
translations importto regenerate the wiring code
For full command reference, see the CLI commands documentation.