#

## :icon-globe:  Internationalization

---

Pagy handles string translation and pluralization using its own efficient i18n implementation.

!!!success
Apps using **only English language**, are supported out of the box **without** any I18n Setup!
!!!

=== :icon-list-ordered:  Setup

All Pagy strings are stored in **dictionary files** within its [locales](https://github.com/ddnexus/pagy/blob/master/gem/locales). These files adopt the same structure as the standard locale files for the `i18n` gem, allowing you to use them seamlessly with both engines.

>>> Pick the I18n engine...

+++ Pagy::I18n

!!!success Recommended: ~18x faster and ~10x lighter
It works seamlessly even if the rest of your app works with the `i18n` gem.
!!!

Set the `Pagy::I18n.locale` for each request. For example:

```rb Controller
before_action { Pagy::I18n.locale = params[:locale] }
```

**Notice**: The default `Pagy::I18n.locale` is `'en'`.

+++ I18n gem

!!!warning Slower
!!!

Switch the translation to the `i18n` gem. Pagy will only provide its dictionaries...

```rb [pagy.rb initializer](/toolbox/configuration/initializer)
Pagy.translate_with_the_slower_i18n_gem!
```
+++

>>>

==- :icon-book:  Sample Dictionary

:::code source="../gem/locales/en.yml" title="en.yml":::

==- :icon-pencil:  Customizing dictionaries

!!!warning IMPORTANT
If you use `Pagy::I18n`, name your custom dictionary as `<locale>.yml`.
!!!

Place your custom dictionaries in a directory and add its path to the I18n pathnames.

```rb [pagy.rb initializer](/toolbox/configuration/initializer)
# Example for Rails:
Pagy::I18n.pathnames << Rails.root.join('config/locales/pagy')
```

==- :icon-mortar-board:&nbsp; Contributing a Language

!!!question

Feel free to ask for further help via [Pagy Support](https://github.com/ddnexus/pagy/discussions/categories/q-a).

!!!

>>> Find the pluralization of your language...

[!badge variant="info" size="s" corners="pill" text="•1"]&nbsp; Locate the file of your locale in the [list of pluralizations](https://github.com/svenfuchs/rails-i18n/tree/master/rails/pluralization)

[!badge variant="info" size="s" corners="pill" text="•2"]&nbsp; Check the pluralization used in it.

[!badge variant="info" size="s" corners="pill" text="•3"]&nbsp; Confirm that Pagy has the same pluralization in the [P18n directory](https://github.com/ddnexus/pagy/blob/master/gem/lib/pagy/modules/i18n/p18n).

||| If missing, you have two choices...

[!badge variant="info" size="s" corners="pill" text="easy"]&nbsp; [Create a new Feature Request](https://github.com/ddnexus/pagy/discussions/new?category=feature-requests) asking for the addition of the pluralization for your locale.

[!badge variant="info" size="s" corners="pill" text="best"]&nbsp; Create a new module for the pluralization _(by adapting the same pluralization from the corresponding rails-i18n file)_ and include tests for it

|||

>>> Duplicate an existing dictionary...

[!badge variant="info" size="s" corners="pill" text="•1"]&nbsp; Pick a _(similarly pluralized)_ dictionary in the [lib/locales](https://github.com/ddnexus/pagy/tree/master/gem/locales).

[!badge variant="info" size="s" corners="pill" text="•2"]&nbsp; Set the `p11n` entry to the right pluralization module name in the [P18n directory](https://github.com/ddnexus/pagy/blob/master/gem/lib/pagy/modules/i18n/p18n).

[!badge variant="info" size="s" corners="pill" text="•3"]&nbsp; Provide the necessary plurals for `aria_label.nav` and `item_name`. <br/>
E.g., with `EastSlavic` rule, provide the plurals for `one`, `few`, `many`, and `other`. With `Other` provide only the `other` value, etc.

>>>

==- :icon-location:&nbsp; Localization

Localization is needed **only** by the calendar with non `en` locales [localization](/toolbox/paginators/calendar/#localization).

===