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.
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 for the full list of supported locale codes.
Summary
Functions
Returns true when locale is one of the supported codes, false otherwise.
Returns the current locale, preferring a process-scoped override over the application-wide default.
Returns the active locale, falling back to :default when none is set.
Sets the locale for the calling process.
Returns the sorted list of all supported locale atoms.
Functions
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
@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}
@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
@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
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.
@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]