Translate React component strings using `useTranslate`

Translate visible strings in your components by replacing hardcoded values with translation keys. The useTranslate hook lets you access translations dynamically, with support for metadata-based values, runtime state, and variable interpolation.

This tutorial shows how to integrate useTranslate in a React component and explains the required configuration to support it.

Copy link to this section

Prerequisites

Before using useTranslate, make sure your application supports internationalization. These are shared prerequisites with Translate your application strings to different languages:

1. Declare locales in the backend using Locale entries in {package}/seed/Locale/*.json.
2. Declare the same locales in the frontend config at {package}/config/UiSdlConfig/default.json, using the i18n.locales field.
3. Add translations in {package}/metadata/Translation/{locale}.csv, mapping keys to localized values.
4. Ensure the platform runtime includes an initialized react-intl provider and Redux store. This is configured automatically by the UI Framework.

Once these are in place, useTranslate will be able to resolve translations correctly in your component.

Copy link to this section

Use the useTranslate hook

Import and call the useTranslate hook inside your component to get a translation function:

import useTranslate from '@c3/sdl-react/hooks/useTranslate';

const MyComponent = () => {
  const translate = useTranslate();

  return <h2>{translate({ key: 'myPackage.component.title', defaultValue: 'Welcome' })}</h2>;
};

You can pass the following options:

• key: A string identifier for the translation
• defaultValue: A fallback if no value is found
• spec: A UiSdlDynamicValueSpec for metadata-based resolution
• variables: An object to interpolate dynamic values
• formats: Optional formatting configuration

Copy link to this section

Replace hardcoded strings

Remove all hardcoded strings in your component and replace them with calls to translate().

✅ Do this:

translate({ key: 'myPackage.button.submit', defaultValue: 'Submit' })

🚫 Avoid:

<button>Submit</button>

This ensures your UI can adapt to locale changes and use platform-driven overrides.

Copy link to this section

Interpolate variables

Pass a second argument to interpolate dynamic values:

translate({ key: 'myPackage.alert.welcome' }, { name: 'Alice' });

In your translation CSV:

myPackage.alert.welcome,Welcome, {name}!

The output becomes:

Welcome, Alice!

Copy link to this section

Use dynamic translation specs

Use spec when receiving a translation key from metadata or when a component is configured dynamically through SDL:

const CustomChart = ({ title }: CustomChartProps) => {
  const translate = useTranslate();

  return <h1>{translate({ spec: title })}</h1>;
};

This resolves the value using the Redux state, component props, and metadata context.

Copy link to this section

Best practices

• Use clear and scoped translation keys: {package}.{component}.{intent}
• Include defaultValue in all calls to support graceful fallback
• Interpolate values instead of concatenating strings
• Keep one CSV file per locale, and update them in sync with new features
• Avoid translation key duplication by starting with a shared en.csv