# translations (https://docs.salla.dev/twilight/react/api/modules/translations)



Use `translations` only to inspect the store's message catalog. For ordinary text use [useTranslation](https://docs.salla.dev/twilight/react/hooks/use-translation): the engine already loads these files for the page's language and builds the i18n instance from them. Unlike the other modules, this one uses the `cdn` and `filesCdn` clients, so it sends none of the store, token or scope headers.

```tsx title="app/components/Debug.tsx"
import { useQuery } from '@tanstack/react-query';
import { getTwilightContext } from '@salla.sa/twilight-theme-engine/tanstack';
import { translations } from '@salla.sa/twilight-theme-engine/api/translations';

export function Debug() {
  const { locale } = getTwilightContext();
  const { data } = useQuery(translations.queries.byLocale(locale));
  const keys = Object.keys(data?.[`${locale}.trans`] ?? {});

  return <p>{keys.length} keys</p>;
}
```

## Methods [#methods]

| Method                  | Parameters                                  | Returns                                    | Request                                                                      | Login needed |
| ----------------------- | ------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------- | ------------ |
| `translations.get`      | `locale: string`                            | `Promise<TranslationMessages \| null>`     | `GET translations/common/{locale}.json` on `https://cdn.files.salla.network` | No           |
| `translations.forStore` | `storeId: string \| number, locale: string` | `Promise<Record<string, unknown> \| null>` | `GET translations/{storeId}/{locale}.json` on the same host                  | No           |
| `translations.merge`    | `common, overrides, locale`                 | `TranslationMessages \| null`              | None: lays the merchant's wording over the platform's                        | No           |

`TranslationMessages` is `Record<string, Record<string, string>>`, keyed by `<locale>.trans`, for example `'ar.trans'`. `get` returns one language, so the object has a single key.

`forStore` is the merchant's own edits to the wording. Most stores have none, so the engine asks for the file only when the language in the store settings has `has_custom_translations` set.

## Queries [#queries]

| Query                                           | Key                                 |
| ----------------------------------------------- | ----------------------------------- |
| `translations.queries.byLocale(locale)`         | `['translations', locale]`          |
| `translations.queries.byStore(storeId, locale)` | `['translations', storeId, locale]` |

Each language is its own file, so the locale is part of the key. `storeId` is `store.id` from the [store settings](https://docs.salla.dev/twilight/react/api/modules/store), not the store identifier the client sends in its header.

## Gotchas [#gotchas]

* **Fallback.** If the platform file for a language is missing, `get` falls back to the older shared file `js/translations.json` on `https://cdn.salla.network`, and returns `null` if that fails too.
* **Errors are swallowed by `get`.** Any failure logs a warning and `get` returns `null`. Each wait is 5 seconds.
* **`forStore` is stricter.** A 404 means "no overrides" and returns `null`, but any other failure throws, so the engine does not cache "no overrides" by mistake.
* **Your own strings.** The store's messages live in the `app` namespace and your theme's locale files in `theme`. See [Add translation keys](https://docs.salla.dev/twilight/react/recipes/add-translation-keys).

## See also [#see-also]

* [Languages and RTL](https://docs.salla.dev/twilight/react/guide/languages-and-rtl)
* [useTranslation](https://docs.salla.dev/twilight/react/hooks/use-translation)
* [store](https://docs.salla.dev/twilight/react/api/modules/store)