# `NeoFaker.Locale`
[🔗](https://github.com/muzhawir/neo_faker/blob/main/lib/neo_faker/locale.ex#L1)

Functions for managing and inspecting the active locale.

This is the single owner of locale state and the list of supported locale
codes. Every other module (including `NeoFaker.Data`) reads locale state
through this module rather than managing it independently.

## Locale support

Many modules accept a `:locale` option. Use `set/1` to override the locale
for the calling process, or pass `locale:` per call. To set a locale for
the whole application instead (e.g. for a Phoenix app), configure
`config :neo_faker, locale: ...`, then see
[Getting Started](https://hexdocs.pm/neo_faker/getting-started.html).

    iex> NeoFaker.Locale.set(:id_id)
    :ok

    iex> NeoFaker.Person.first_name()  # uses :id_id for this process
    "Jaka"

    iex> NeoFaker.Person.first_name(locale: :en_us)  # overrides per call
    "José"

See the [available locales](https://hexdocs.pm/neo_faker/locales.html)
for the full list of supported locale codes.

# `available?`
*since 0.15.0* 

```elixir
@spec available?(atom()) :: boolean()
```

Returns `true` when `locale` is one of the supported codes, `false` otherwise.

`:default` is not treated as "available" here; check for it explicitly.

## Examples

    iex> NeoFaker.Locale.available?(:id_id)
    true

    iex> NeoFaker.Locale.available?(:bogus)
    false

# `fetch`
*since 0.15.0* 

```elixir
@spec fetch() :: {:ok, atom()} | :error
```

Returns the current locale, preferring a process-scoped override over the
application-wide default.

Checks, in order: a locale set for the calling process via `set/1`, then
`config :neo_faker, locale: ...`. Returns `{:ok, locale}` when either
source has a value, or `:error` when neither does. Raises `ArgumentError` if
the application-configured value is not an atom, or is an unsupported atom
(i.e. not `:default` and not in `supported/0`), which can happen if
`config :neo_faker, locale: ...` is set directly instead of going through
`set/1`, which validates before storing.

## Examples

    iex> NeoFaker.Locale.set(:en_us)
    :ok

    iex> NeoFaker.Locale.fetch()
    {:ok, :en_us}

# `get`
*since 0.15.0* 

```elixir
@spec get() :: atom()
```

Returns the active locale, falling back to `:default` when none is set.

Unlike `fetch/0`, this function always returns an atom and never returns
`:error`, making it convenient for use inside generator functions.

## Examples

    iex> NeoFaker.Locale.set(:en_us)
    :ok

    iex> NeoFaker.Locale.get()
    :en_us

# `set`
*since 0.15.0* 

```elixir
@spec set(atom()) :: :ok
```

Sets the locale for the calling process.

The override is process-scoped (stored in the process dictionary), so
concurrent processes, including `async: true` ExUnit tests, never
interfere with each other. It does not touch `config :neo_faker, locale:
...`, which remains the fallback for any process that hasn't called this
function. See the [available locales](https://hexdocs.pm/neo_faker/locales.html)
for the full list of supported codes. Raises `ArgumentError` if a non-atom
or unsupported locale is provided.

## Examples

    iex> NeoFaker.Locale.set(:id_id)
    :ok

    iex> NeoFaker.Locale.set(:en_us)
    :ok

    iex> NeoFaker.Locale.set(:default)
    :ok

    iex> NeoFaker.Locale.set(:bogus)
    ** (ArgumentError) Unsupported locale :bogus. Expected one of [:default, :en_us, :id_id] or see the available locales documentation.

The list of supported locales in the error message is built from `supported/0`,
so it always reflects the actual supported set.

# `supported`
*since 0.15.0* 

```elixir
@spec supported() :: [atom()]
```

Returns the sorted list of all supported locale atoms.

The `:default` sentinel is **not** included; use `available?/1` or check
for `:default` explicitly.

## Examples

    iex> NeoFaker.Locale.supported()
    [:en_us, :id_id]

---

*Consult [api-reference.md](api-reference.md) for complete listing*
