# 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()`](#uselocales) section.

This is a React integration for this package:

{% content-ref url="../services/translator" %}
[translator](https://docs.corets.io/services/translator)
{% 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"))
```