# Step 4 · Set up localisation and time handling

Canonical page: https://docs.ovok.com/guides/medication-reminder/set-up-localisation-and-time-handling

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

An i18next instance that reads published UI strings from Ovok CMS and a single, explicit rule for interpreting medication schedule times.

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

- The Expo app and sandbox tenant code from steps 1 and 2.
- CMS enabled in the sandbox project.
- `i18next` and `react-i18next` installed.

## The implementation [#the-implementation]

### Author the English strings in the Console [#author-the-english-strings-in-the-console]

Create published documents in the `translations` collection for the groups below. Every key used by the tutorial UI needs an English value; add the German values in step 10. For the React Native SDK auth forms, use the `sign-in` and `register` slugs so CMS values override the built-in English strings. Do not create local `en.json` files; the app loads these strings from Ovok CMS. The collection is public tenant content, so never place patient data, tokens, or project secrets in it.

| Document slug | Keys used in this tutorial |
| --- | --- |
| `medication` | `todayTitle`, `loading`, `loadError`, `emptyPlan`, `noSupportedSchedule`, `morning`, `afternoon`, `evening`, `night`, `upcoming`, `due`, `taken`, `skipped`, `missed`, `missedMessage`, `unknownName`, `requestStatus`, `dose`, `startDate`, `endDate`, `notificationChannel`, `reminderTitle`, `reminderBody`, `reminderScheduleError`, `saving`, `markTaken`, `markSkipped`, `patientReported`, `reportError`, `retryReport`, `historyTitle`, `filterAll`, `filter7Days`, `filter30Days`, `noHistory`, `recordedStatus`, `viewDetails`, `notInPlan`, `lastSynced`, `offlineCacheError`, `pendingSync`, `syncError` |
| `settings` | `title`, `profile`, `language`, `english`, `german`, `reminders`, `privacyAndConsent`, `signOut`, `appInformation`, `notificationsDenied` |
| `sign-in` | Keep the full key set listed in the [React Native SDK sign-in reference](/native-sdk/guide/components/auth/sign-in); this slug replaces the shared group. |
| `register` | Keep the full key set listed in the [React Native SDK registration reference](/native-sdk/guide/components/auth/register), plus `registrationFailed` and `tryAgain` for the app-owned registration alert; this slug replaces the shared group. |

Publish the following English `key` → `value` pairs for `medication` and `settings`. Keep the `{{...}}` interpolation names intact. The Register form's remaining keys come from the React Native SDK reference linked above.

### `medication` English values [#medication-english-values]

| Key | English value |
| --- | --- |
| `todayTitle` | Today's medications |
| `loading` | Loading… |
| `loadError` | We couldn't load this information. Try again. |
| `emptyPlan` | No active medication plan is available for this account. |
| `noSupportedSchedule` | No supported schedule details are available yet. |
| `morning` | Morning |
| `afternoon` | Afternoon |
| `evening` | Evening |
| `night` | Night |
| `upcoming` | Upcoming |
| `due` | Due |
| `taken` | Taken |
| `skipped` | Skipped |
| `missed` | Not recorded |
| `missedMessage` | This dose was not recorded as taken. |
| `unknownName` | Medication name not provided |
| `requestStatus` | Plan status: `{{status}}` |
| `dose` | `{{value}}` `{{unit}}` |
| `startDate` | Starts `{{date}}` |
| `endDate` | Ends `{{date}}` |
| `notificationChannel` | Reminders |
| `reminderTitle` | Reminder |
| `reminderBody` | You have a scheduled reminder. Open the app to view details. |
| `reminderScheduleError` | We couldn't update reminders. Open Settings and try again. |
| `saving` | Saving your response… |
| `markTaken` | Mark as taken |
| `markSkipped` | Mark as skipped |
| `patientReported` | Patient reported |
| `reportError` | We couldn't save this response. Try again. |
| `retryReport` | Retry sending response |
| `historyTitle` | Medication history |
| `filterAll` | All time |
| `filter7Days` | Last 7 days |
| `filter30Days` | Last 30 days |
| `noHistory` | No medication reports in this period. |
| `recordedStatus` | Recorded status: `{{status}}` |
| `viewDetails` | View details |
| `notInPlan` | This medication is not in the current plan. |
| `lastSynced` | Last synced `{{date}}` |
| `offlineCacheError` | This information could not be saved for offline use. It may not be available without a connection next time. |
| `pendingSync` | Your response is saved on this device and is waiting to sync. |
| `syncError` | A saved response needs attention before it can sync. |

### `settings` English values [#settings-english-values]

| Key | English value |
| --- | --- |
| `title` | Settings |
| `profile` | Patient ID |
| `language` | Language |
| `english` | English |
| `german` | Deutsch |
| `reminders` | Reminders |
| `privacyAndConsent` | Privacy and consent |
| `signOut` | Sign out |
| `appInformation` | App information |
| `notificationsDenied` | Notifications are turned off. You can change this in device settings. |

For `register.registrationFailed`, use **We couldn't create your account.**; for `register.tryAgain`, use **Check your details and try again.** These are tutorial-owned additions. Keep the React Native SDK's built-in English authentication text as the fallback for other keys.

The hook merges the CMS response into i18next's single `translation` namespace. A slug and key become a dotted lookup, such as `medication.todayTitle`; use `t("medication.todayTitle")`, not an i18next namespace separator such as `t("medication:todayTitle")`.

Follow [Use Ovok CMS with i18n](/cms/use-ovok-cms-with-i18n) for the supported fields, language codes, publication, and fallback behavior.

### Initialize i18next without bundled app dictionaries [#initialize-i18next-without-bundled-app-dictionaries]

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;
```

Import the React Native SDK's built-in auth strings and create `src/localization/localization-gate.tsx`. The gate waits for the initial CMS read before showing screens, so the first render does not expose raw translation keys:

```tsx
import "@ovok/native/auth";
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` is called once near the root, below the `I18nextProvider` added in step 5. It observes the active locale and refetches when the user changes languages. The retry text above is a bootstrap fallback; it is not a replacement for the app's CMS strings. The authentication module import registers the React Native SDK's built-in auth strings so missing CMS keys still have the SDK's English fallback.

### Define one schedule-time rule [#define-one-schedule-time-rule]

FHIR `Timing.repeat.timeOfDay` is a local clock time without a timezone offset. For this tutorial, interpret it in the device's current timezone and preserve that wall-clock value when the user travels. Display times with `Intl.DateTimeFormat`; do not convert the plan's `timeOfDay` to UTC and write it back.

Create `src/localization/schedule-time.ts` for the device-local time rule:

```ts
export function atDeviceLocalTime(day: Date, fhirTime: string): Date | undefined {
  const [hour, minute, seconds = "0"] = fhirTime.split(":");
  const second = Number(seconds.split(".")[0]);
  const result = new Date(
    day.getFullYear(),
    day.getMonth(),
    day.getDate(),
    Number(hour),
    Number(minute),
    second,
    0,
  );

  // A wall-clock time inside the spring DST gap does not exist on this date.
  if (
    result.getHours() !== Number(hour) ||
    result.getMinutes() !== Number(minute) ||
    result.getSeconds() !== second
  ) {
    return undefined;
  }

  return result;
}

export function formatScheduleTime(date: Date, locale: string): string {
  return new Intl.DateTimeFormat(locale, {
    hour: "numeric",
    minute: "2-digit",
  }).format(date);
}
```

This tutorial's three sample times avoid the DST spring gap. A repeated wall-clock time in the autumn overlap is resolved by the device runtime; if your care workflow needs a specific “first” or “second” occurrence, choose and test that rule explicitly. When the app returns to the foreground, compare `Intl.DateTimeFormat().resolvedOptions().timeZone` with the last scheduled zone and rebuild future local notifications if it changed. The app cannot promise to react to a timezone change while it is not running.

Only schedule explicit daily `timeOfDay` entries with the simple daily `period` used in the sample plan. `dayOfWeek` and `boundsPeriod` also affect whether an occurrence is due. If a request uses a more complex `Timing` pattern, do not silently approximate it; show the supplied instructions and have the product owner define the schedule interpretation.

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

- CMS translations hold public interface text only; patient-specific content remains in FHIR and is rendered at runtime.
- Localisation changes display formatting. It does not change the meaning or timezone interpretation of a stored schedule.
- A timezone change triggers a local reschedule; it does not alter `MedicationRequest`.

## Expected result [#expected-result]

The app can render English labels from published CMS translations and has a helper that maps supported FHIR local times to device-local `Date` values without silently moving a non-existent DST time.

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

- **The app shows translation keys:** check CMS publication, tenant code, locale, and that `CmsTranslations` uses the same i18next instance as React screens.
- **A schedule appears one hour off:** confirm that code treats `timeOfDay` as local wall-clock time and does not parse it as UTC.
- **An occurrence disappears on a DST transition:** the helper intentionally returns no instant for a nonexistent local time. Define a product-approved handling rule rather than shifting it silently.

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

Previous: [step 3: model the medication plan](/guides/medication-reminder/model-the-medication-plan) · Continue to [step 5: initialise Ovok and authentication](/guides/medication-reminder/initialise-ovok-and-authentication).
