# useTranslator

Source code is hosted on [GitHub](https://github.com/corets/use-translator)

{% tabs %}
{% tab title="yarn" %}

```bash
yarn add @corets/use-translator
```

{% endtab %}

{% tab title="npm" %}

```bash
npm install --save @corets/use-translator
```

{% endtab %}
{% endtabs %}

To learn how to use translations in a static way check the [`useLocales()`](/hooks/use-translator.md#uselocales) section.

This is a React integration for this package:

{% content-ref url="/pages/-MeeFAgcZV96KXm0W1WU" %}
[Translator](/services/translator.md)
{% endcontent-ref %}

## &#x20;\<TranslatorProvider /> <a href="#translatorcontext" id="translatorcontext"></a>

You can share a translator instance through a dedicated `TranslatorProvider` component. Methods like `useTranslator`, `useTranslate` and `useLanguage` automatically try to find an instance in the context, so you don't have to pass it manually. This is the recommended way to use this library:

```typescript
import React from "react"
import { render } from "react-dom"
import { createTranslator } from "@corets/translator"
import {
  TranslatorProvider,
  useTranslator,
  useTranslate,
  useLanguage,
} from "@corets/use-translator"

const translations = {
  en: {
    title: "Foo",
    nested: { title: "Bar" }
  }
}

const translator = createTranslator(translations, { language: "en" })

const Example = () => {
  const t = useTranslate()

  return <div>Regular access: {t("title")}</div>
}

render(
  <TranslatorProvider instance={translator}>
    <Example />
  </TranslatorProvider>,
  document.getElementById("root")
)
```

## useLocales()

Translations can be accessed statically thanks to the `createTranslatorAccessor` helper. All you have to do is to create a small hook where you choose your default / most up to date language that is used for the static typing.

```typescript
import React from "react"
import { render } from "react-dom"
import { createTranslatorAccessor } from "@corets/translator"

const translations = {
  en: {
    title: "Foo",
    nested: { title: "Bar" }
  }
}

const translator = createTranslator(translations, { language: "en" })

const useLocales = () => createTanslatorAccessor(useTranslator(translator), translations.en)

const Example () => {
  const loc = useLocales()
  
  return <div>{loc.nested.title.get()}</div>
}

render(<Example />, document.getElementById("root"))
```

## useTranslator() <a href="#usetranslator" id="usetranslator"></a>

Use translator inside React components:

```typescript
import React from "react"
import { render } from "react-dom"
import { createTranslator } from "@corets/translator"
import { useTranslator } from "@corets/use-translator"

const translations = {
  en: {
    title: "Foo",
    nested: { title: "Bar" }
  }
}

const translator = createTranslator(translations, { language: "en" })

const Example = () => {
  const translator = useTranslator(translator)
  
  return (
    <div>Title: {translator.get("title")}</div>
  )
}

render(<Example />, document.getElementById("root"))
```

## useTranslate() <a href="#usetranslate" id="usetranslate"></a>

Use a translation function inside React components:

```typescript
import React from "react"
import { render } from "react-dom"
import { createTranslator } from "@corets/translator"
import { useTranslate } from "@corets/use-translator"

const translations = {
  en: {
    title: "Foo",
    nested: { title: "Bar" }
  }
}

const translator = createTranslator(translations, { language: "en" })

const Exymple = () => {
  const t = useTranslate(translator)
  const tt = useTranslate(translator, { "nested" })
  
  return (
    <div>
      <div>Title: {t("title")}</div>
      <div>Nested title: {tt("title")}, same as: {t("nested.title")}</div>
    </div>
  )
}

render(<Example />, document.getElementById("root"))
```

## useLanguage() <a href="#uselanguage" id="uselanguage"></a>

Use language related information inside your React components:

```typescript
import React from "react"
import { render } from "react-dom"
import { createTranslator } from "@corets/translator"
import { useLanguage } from "@corets/use-translator"

const translations = {
  en: {
    title: "Foo",
    nested: { title: "Bar" }
  }
}

const translator = createTranslator(translations, { language: "en" })

const Example = () => {
  const language = useLanguage(translator)
  
  return (
    <div>
      <div>Current: {language.current}</div>
      <div>Fallback: {language.fallback}</div>
      <div>Available: {JSON.stringify(language.available)}</div>
      <button onClick={()=> language.set("de")}>Set language to "de"</button>
    </div>
  )
}

render(<Example />, document.getElementById("root"))
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.corets.io/hooks/use-translator.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.