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

LocaleCountryLanguage
:default🌐 N/AEnglish (US), not country-specific
:id_id🇮🇩 IndonesiaBahasa 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:

  1. Per call. Pass locale: :id_id (or any supported locale) directly to the function. This overrides everything else for that one call only.
  2. Per process. Call NeoFaker.Locale.set/1 once, 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 inside async: true tests without affecting other tests running concurrently.
  3. Application-wide. Set config :neo_faker, locale: ... in your config files. This is the fallback used by any process that hasn't called NeoFaker.Locale.set/1, and the right choice for a whole application's default (e.g. a Phoenix app's config/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.