# Step 3 · Configure localisation with Ovok CMS

Canonical page: https://docs.ovok.com/guides/chf-remote-monitoring/configure-localisation

An i18next setup that reads the app's published strings from Ovok CMS. Translation content lives in the Console, not in JSON files bundled with the app. When a translator updates a published value, the app can receive it without a new native release.

## Before you begin [#before-you-begin]

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

## Build it [Client-side] [#build-it-client-side]

### Add the first translation group in Ovok Console [#add-the-first-translation-group-in-ovok-console]

In the Console, open the sandbox project's CMS and create a document in the built-in `translations` collection:

| Field | Value |
| --- | --- |
| `slug` | `app` |
| `status` | `published` |
| `strings` | Add `title`, `welcome`, and `description` keys with English values. |

For example, the `welcome` key can have the English value `Welcome`. The CMS document stores localized values; it is not a file in the app. The `translations` collection is open by default, so the app needs its tenant code but no CMS API key. Publish this document on the sandbox, the API the app reads below. See [Use Ovok CMS with i18n](/cms/use-ovok-cms-with-i18n) for the Console fields and fallback rules.

### Initialize i18next without local translation resources [#initialize-i18next-without-local-translation-resources]

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 intentionally no `resources` option and no `locales/en.json`: the CMS supplies app strings. Importing `@ovok/native/auth` registers the SDK's built-in English auth copy. When the CMS hook loads a matching group such as `sign-in`, its published values can replace those defaults.

### Load CMS strings and gate the first screen [#load-cms-strings-and-gate-the-first-screen]

Create `src/localization/localization-gate.tsx`:

~~~tsx
import * as React from "react";
import { ActivityIndicator, View } from "react-native";
import { Button, Text } from "react-native-paper";
import { useCmsTranslations } from "@ovok/native/cms";

import { localizationReady } from "./i18n";

function CmsTranslations({ children }: React.PropsWithChildren) {
  const { data, loading, error, refetch } = useCmsTranslations();

  if (error) {
    return (
      <View>
        <Text>App language content could not be loaded.</Text>
        <Button onPress={refetch}>Retry</Button>
      </View>
    );
  }
  if (loading || !data) return <ActivityIndicator />;

  return children;
}

export function LocalizationGate({ children }: React.PropsWithChildren) {
  const [ready, setReady] = React.useState(false);

  React.useEffect(() => {
    void localizationReady.then(() => setReady(true));
  }, []);

  if (!ready) return <ActivityIndicator />;
  return <CmsTranslations>{children}</CmsTranslations>;
}
~~~

`useCmsTranslations` reads the current i18next language, fetches the published CMS translation groups for it, and merges them into the `translation` namespace. The client's tenant code lets this request run before sign-in. It refetches when the language changes. The inline error and retry text are a bootstrap fallback for a CMS outage; they are not the app's translation catalog.

In step 5, place `LocalizationGate` inside `OvokProvider` and the app `ThemeProvider`, around the Expo Router stack. The gate waits for i18next and the first CMS response before showing screens that use translated text.

Use the starter group in a screen:

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

export function WelcomeScreen() {
  const { t } = useTranslation();
  return <Text>{t("app.welcome")}</Text>;
}
~~~

## Key decisions [#key-decisions]

- Keep application copy in the project's CMS `translations` collection. Do not add app translation JSON files.
- Use bare CMS language codes such as `en` and `de`. The CMS accepts every ISO 639-1 language, but the Ovok SDKs read only `de`, `en`, `fr`, and `es`. The app's allowed language list should match languages actually published for its tenant.
- A draft group is not delivered. Publish the group on the same Ovok API the app reads.
- CMS text is public content. Never put patient data, secrets, or private project configuration in translation values.
- The system Bluetooth permission prompt is native platform copy, not CMS content. Step 10 explains where that text must be localized.

## Verify your integration [#verify-your-integration]

The app initializes i18next without bundled translation dictionaries, loads the published `app` group from the sandbox CMS, and renders `app.welcome` from the CMS response.

## Troubleshooting [#troubleshooting]

- **The app stays on the loading screen:** confirm CMS is enabled, the `app` group is published, and its tenant matches the app configuration.
- **The screen shows `app.welcome`:** check that the group slug is `app` and the key is `welcome`; confirm the document is published.
- **The CMS request returns an unknown tenant:** use the tenant code from the same sandbox project and allow time for a newly created tenant code to become available.
- **The language changes but text does not:** make sure a published group exists for the selected language. Missing CMS values fall back to English field by field.

## Next step [#next-step]

Continue to [step 4: choose connected devices](/guides/chf-remote-monitoring/choose-connected-devices).
