NeoFaker supports locale-specific data for realistic test output. Almost every function that
accepts a :locale option is locale-aware, and loads its data from
priv/data/<locale>/<domain>/<file>.exs inside the package. If the requested locale has no data
file for a given domain/file combination, NeoFaker falls back to priv/data/default/ (generic
English (US) data) for that lookup only, instead of raising.
Available Locales
| Locale | Country | Language |
|---|---|---|
:default | 🌐 N/A | English (US), not country-specific |
:id_id | 🇮🇩 Indonesia | Bahasa Indonesia |
:default isn't itself a locale code. It's the baseline dataset every other locale falls back
to. :en_us is accepted as a locale value, but it has no dataset of its own yet, so it resolves
to :default data. :id_id has its own data for several domains (Address, App, Color,
Person), and falls back to :default for the rest.
Setting the locale
There are three ways to control which locale a function draws from, checked in this order:
- Per call. Pass
locale: :id_id(or any supported locale) directly to the function. This overrides everything else for that one call only. - Per process. Call
NeoFaker.Locale.set/1once, and every subsequent call in that process uses it until changed. This is process-scoped (stored in the process dictionary), so it's safe to use insideasync: truetests without affecting other tests running concurrently. - Application-wide. Set
config :neo_faker, locale: ...in your config files. This is the fallback used by any process that hasn't calledNeoFaker.Locale.set/1, and the right choice for a whole application's default (e.g. a Phoenix app'sconfig/dev.exs).
# Per call, overrides everything else for this one call
iex> NeoFaker.App.description(locale: :id_id)
"Penghasil data palsu untuk pengujian dan lingkungan pengembangan Elixir."
# Per process, affects every call in the current process from here on
iex> NeoFaker.Locale.set(:id_id)
:ok
iex> NeoFaker.App.description()
"Penghasil data palsu untuk pengujian dan lingkungan pengembangan Elixir."If you pass an unsupported locale to NeoFaker.Locale.set/1 or a function's :locale option,
NeoFaker raises ArgumentError listing the currently supported locales. That's the same list
shown in the table above and returned by NeoFaker.Locale.supported/0.
See the configuration instructions for how to set the application-wide default, including notes for Phoenix projects.
Locale-exclusive generators
Some data only makes sense for a single locale and isn't expressed as a :locale option on a
shared function. For example, a US Social Security Number has no Indonesian equivalent to fall
back to. These live under their own NeoFaker.Locales.* namespace instead:
iex> NeoFaker.Locales.EnUs.Person.ssn()
"184-63-2006"
iex> NeoFaker.Locales.IdId.Person.nik()
"7645504903500640"See the Locale Cheat Sheet for a quick reference grouped by locale, or the "Locale Random Generators" group in the API Reference for the full module docs.
Adding a new locale
A new locale needs a directory under priv/data/<locale>/ mirroring the domains it covers. Only
the files you provide are used; anything missing falls back to :default, so a partial locale is
valid. It also needs its code added to the @supported_locales list in NeoFaker.Locale (kept
alphabetically sorted). Locale-exclusive generators, if any, go under
lib/neo_faker/locales/<locale>/.
See Adding a Locale for the full contributor walkthrough, from picking a locale code through opening the pull request. Open an issue or pull request on GitHub to propose one.