# CMS content and translations

Canonical page: https://docs.ovok.com/native-sdk/guide/modules/cms

Use the CMS hooks when a screen needs content managed in Ovok CMS, such as a legal page, release notes, or localized app copy. The hooks return request state; they do not render a screen or choose navigation, caching UI, or empty and error states for the host app.

CMS locale follows the app's `react-i18next` language. The SDK maps that language to a CMS locale (for example, `de-DE` to `de`) and updates requests when the app language changes. Pass `options.locale` when a request needs a different locale.

## Read a CMS document [#read-a-cms-document]

Import the hooks from the optional `cms` subpath:

```tsx
import { useCmsDocument, useCmsLocale } from "@ovok/native/cms";

type Article = {
  title: string;
  body: string;
};

function ArticleScreen({ slug }: { slug: string }) {
  const locale = useCmsLocale();
  const request = useCmsDocument<Article>("articles", slug);

  return <ArticleView locale={locale} request={request} />;
}
```

Use `useCmsDocument(collection, slug, options)` for one entry and `useCmsDocuments(collection, options)` for a collection page. The generic type describes the content shape your app expects; keep it aligned with the CMS schema. Handle loading, missing content, request errors, and retry behavior in the host screen using the returned `OvokRequestState`.

For the built-in legal page and release notes endpoints, use `useLegalPage(slug, options)` and `useReleaseNotes(options)`. Legal pages can be read before sign-in when you provide the tenant code. Release notes require a session. The hooks use the current app locale unless `options.locale` overrides it.

## Load CMS translations [#load-cms-translations]

Call `useCmsTranslations` once in a component below the app's i18next provider, usually near the application root:

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

function CmsTranslationBootstrap({ tenantCode }: { tenantCode: string }) {
  useCmsTranslations({ tenantCode });
  return null;
}
```

The hook loads the CMS `translations` collection for the current CMS locale and merges it into the i18next `translation` namespace. App-owned strings take precedence. CMS strings can replace the SDK's built-in English defaults, while an explicit `options.locale` targets a specific CMS locale. It returns the underlying `OvokRequestState`; surface failures through host-owned logging or UI if the translations are required for the screen.

For a signed-out app, pass `tenantCode` so the CMS can resolve the tenant. Place the hook under the i18next provider and call it once; do not add it to every screen. A language change triggers a request for the new CMS locale.

## Choose the right hook [#choose-the-right-hook]

| Need | Hook |
| --- | --- |
| One document from a collection | `useCmsDocument(collection, slug, options)` |
| A page of collection documents | `useCmsDocuments(collection, options)` |
| A legal page that can be loaded before sign-in with `tenantCode` | `useLegalPage(slug, options)` |
| Release notes for a signed-in user | `useReleaseNotes(options)` |
| App language as a CMS locale | `useCmsLocale()` |
| CMS-backed translations in i18next | `useCmsTranslations(options)` |

The `cms` hooks read CMS data. For app-owned content cards and FHIR Composition details, see [Content components](/native-sdk/guide/modules/content).

## References [#references]

See the [CMS hook reference](/native-sdk/guide/components/cms/) for imports and the generated signatures for each export.

## API reference [#api-reference]

Every export of `@ovok/native/cms`, with signatures, props and types, is in the [`cms` API reference](/native-sdk/reference/cms).