API reference

Updated Nov 9, 2026 v0.0.1

These are the public modules of Mishka Slug 0.0.1: MishkaSlug, MishkaSlug.Options, MishkaSlug.Scripts, MishkaSlug.Messages and MishkaSlug.Change. Each function lists its return values. For the options, see Options.

MishkaSlug

Function	Returns
`slugify(text, opts \\ [])`	`{:ok, slug}` or `{:error, reason}`. Use it for anything a user typed.
`slugify!(text, opts \\ [])`	The slug, or it raises `ArgumentError` (`"cannot make a slug: :empty"`). Use it only when the text is known to have letters or digits.

Invalid options raise ArgumentError in both. A text that is not a string raises FunctionClauseError.

Error reasons

Reason	When
`:empty`	Nothing is left: `""`, `"😀🚀"`, `"---"`.
`:no_allowed_script`	The text has letters or digits, but none is in a script of `:locales`.
`:invalid_utf8`	The binary is not UTF-8.
`:mixed_scripts`	A word mixes scripts and `mixed_scripts: :reject` is set.
`{:unknown_locale, code}`	A code in `:locales` is neither in the built-in table nor known to the resolver.

MishkaSlug.Options

Function	Returns
`validate(opts)`	`{:ok, opts}` with every default filled in, or `{:error, message}`.
`validate!(opts)`	The options, or it raises `ArgumentError`.

MishkaSlug.Scripts

Function	Returns
`for_locales(locales, resolver \\ nil)`	`{:ok, scripts}` with `:latin` always added, `{:ok, :any}` for an empty list, or `{:error, {:unknown_locale, code}}`.
`from_iso15924(code)`	`{:ok, [script]}` for a script code (`"Arab"` or `:Cyrl`, in any case), or `:error` for a script the library does not know.
`language(locale)`	The lowercased language part of a code.
`split(word, allowed, mode)`	`{:ok, parts}`, or `{:error, :mixed_scripts}` when `mode` is `:reject` and the word changes script.

elixir

MishkaSlug.Scripts.for_locales(["fa", "en"])
#=> {:ok, [:arabic, :latin]}

MishkaSlug.Scripts.for_locales([])
#=> {:ok, :any}

MishkaSlug.Scripts.for_locales(["ja"])
#=> {:ok, [:han, :hiragana, :katakana, :latin]}

MishkaSlug.Scripts.for_locales(["sr-Latn"])
#=> {:ok, [:latin]}

MishkaSlug.Scripts.for_locales(["xx"])
#=> {:error, {:unknown_locale, "xx"}}

MishkaSlug.Scripts.from_iso15924("Arab")
#=> {:ok, [:arabic]}

MishkaSlug.Scripts.from_iso15924(:Jpan)
#=> {:ok, [:han, :hiragana, :katakana]}

MishkaSlug.Scripts.from_iso15924("Tibt")
#=> :error

MishkaSlug.Scripts.language("pt-BR")
#=> "pt"

MishkaSlug.Scripts.split("pаypal", [:latin], :split)
#=> {:ok, ["p", "ypal"]}

The script atoms are :latin, :arabic, :hebrew, :cyrillic, :greek, :armenian, :georgian, :han, :hiragana, :katakana, :hangul, :bopomofo, :devanagari, :bengali, :gujarati, :gurmukhi, :kannada, :malayalam, :sinhala, :tamil, :telugu, :thai, :lao, :khmer, :myanmar and :ethiopic.

MishkaSlug.Messages

Function	Returns
`error(reason)`	The translated message for a reason of `slugify/2`.
`not_a_string()`	The message for a value that is not a string: `"is not a string value"`.
`gettext_backend()`	The Gettext backend in use: the `:gettext_backend` of the `:mishka_slug` config, or `MishkaSlug.Gettext`.

See Handle errors and translate messages for the texts.

MishkaSlug.Change

An Ash change that writes a slug. It is compiled only when the project has Ash. It accepts every option of slugify/2, except that :language and :locales take more here. init/1 returns an error for an unknown option or an invalid value, so a typo fails when the resource compiles.

Option	Default	Meaning
`:from`	required	The attribute or argument the slug is made from.
`:into`	the `:from` value	The attribute that gets the slug.
`:skip_if_present?`	`false`	`true` leaves the slug alone when the action already sets `:into`.
`:language`	`nil`	An attribute or argument name read from the changeset, or a fixed code such as `"fa"`.
`:locales`	`[]`	A list of codes, or `{module, function, args}` called as `module.function(changeset, ...args)`.

What the change does:

It reads :from from the action's arguments or changes. When it is not there, the change does nothing, so an update that does not touch the title keeps its slug.
A value that is not a string, or a title that gives no slug, is a changeset error on :from. The slug attribute is never set to nil or an empty string.
Error texts go through Gettext in the locale of the calling process.
When you do not pass :max_length, the max_length constraint of the :into attribute is used.
A ci_string attribute works as :from.
It supports atomic updates when :from is a plain value. An expression is :not_atomic.

Function	Returns
`slug_options(opts, changeset)`	The `slugify/2` options the change would use: language and locales resolved against the changeset, and `:max_length` filled from the attribute.