# Step 3 · Configure localisation with Ovok CMS

Canonical page: https://docs.ovok.com/guides/type-2-diabetes/configure-localisation

## What we are building [#what-we-are-building]

An i18next instance that reads application interface text from the Ovok CMS `translations` collection. The Questionnaire remains a governed FHIR clinical artifact; it is not copied into CMS strings or casually machine-translated.

## What you should already have [#what-you-should-already-have]

- The app and `ovokConfig` from steps 1–2.
- Ovok CMS enabled for the sandbox project.
- `i18next` and `react-i18next` installed.

## The implementation [#the-implementation]

### Publish an English translation group in Console [#publish-an-english-translation-group-in-console]

In the sandbox CMS, create and publish a `translations` document with slug `screening`. Add app-owned keys for navigation, status, errors, buttons, and screen labels. Use the same groups for all later steps, or add one per screen if that is easier for translators to maintain.

Publish English strings on the sandbox before opening the app. The `translations` collection is public by default, so the app uses its tenant code; do not put patient data or secrets in this collection. See [Use Ovok CMS with i18n](/cms/use-ovok-cms-with-i18n) for Console fields, locale fallback, and caching.

### Initialize i18next with no bundled UI dictionary [#initialize-i18next-with-no-bundled-ui-dictionary]

Create `src/localization/i18n.ts`:

```ts
import "@ovok/native/auth";
import i18n from "i18next";
import { initReactI18next } from "react-i18next";

export const localizationReady = i18n.use(initReactI18next).init({
  lng: "en",
  fallbackLng: "en",
  supportedLngs: ["en", "de"],
  interpolation: { escapeValue: false },
  react: { useSuspense: false },
});

export default i18n;
```

There is no local app translation JSON. Importing the auth module registers native English auth labels; the CMS supplies app-specific labels and can override SDK groups when published.

### Load published CMS translations at the app root [#load-published-cms-translations-at-the-app-root]

Create `src/localization/cms-translations.tsx`:

```tsx
import { useCmsTranslations } from "@ovok/native/cms";

export function CmsTranslations() {
  useCmsTranslations();

  return null;
}
```

Mount `<CmsTranslations />` once under `OvokProvider` and the initialized i18next instance, as part of the root layout in step 6. The hook merges published groups into i18next and reloads when the language changes. The client's tenant code lets this first load happen before patient sign-in.

Use translated UI copy in screens:

```tsx
import { useTranslation } from "react-i18next";
import { Text } from "react-native";

export function ScreeningTitle() {
  const { t } = useTranslation("translation", { keyPrefix: "screening" });
  return <Text>{t("title", "Diabetes risk screening")}</Text>;
}
```

The second argument is a runtime fallback for an unpublished key during development. It is not a translation catalog; publish the final text in the CMS.

## Important Ovok decisions [#important-ovok-decisions]

- CMS stores app-owned interface text. The licensed FINDRISC Questionnaire carries its own approved clinical wording and answer options.
- Publish the translation group on the same Ovok API the app reads. A draft is not delivered.
- The UI language may use a regional tag such as `de-DE`; the CMS reads a supported base locale such as `de`.
- Native permission prompts are platform configuration strings. They are not automatically replaced by CMS content.

## Expected result [#expected-result]

The root app can mount the CMS hook, and app screens can resolve `screening.*` keys from published CMS translations with English fallback.

## Common errors and troubleshooting [#common-errors-and-troubleshooting]

- **Text shows its key:** check the `screening` group slug, key name, published status, and tenant.
- **CMS load fails before sign-in:** ensure the `Ovok` client has the sandbox `tenantCode`.
- **German labels still show English:** add and publish the German group; set i18next to the locale you published.
- **FINDRISC text differs from the approved instrument:** do not fix it in CMS. Restore the approved Questionnaire version and review it with the content owner.

## Previous / Next [#previous--next]

[Previous: create and configure the Ovok project](/guides/type-2-diabetes/create-and-configure-the-ovok-project) · [Next: choose the glucose device](/guides/type-2-diabetes/choose-the-glucose-device)
