Mishka
Slug

Keep the scripts your site allows

v0.0.1

This guide sets two things for MishkaSlug.slugify/2: the language of one title (language:) and the languages of the whole site (locales:). The first changes how letters are folded and spelled. The second decides which scripts may appear in a slug. You finish with a slug that holds only the scripts of your site.

Before you begin

  • Mishka Slug installed. See Get Started.
  • The language codes of your site, such as fa and en. A code like pt-br is read by its language part.

Set the language of a title

Pass language: when you know the language of the text. It changes three things.

  • fa, ur and ckb fold the Arabic letters ي ى ك into the Persian ی ک, so the same word typed on an Arabic keyboard gives one slug.
  • de, da, ca, sr and bs spell Latin letters their own way.
  • tr and az lowercase I to ı.
elixir
MishkaSlug.slugify("كتاب يك", language: "fa")
#=> {:ok, "کتاب-یک"}

MishkaSlug.slugify("كتاب جديد", language: "ar")
#=> {:ok, "كتاب-جديد"}

MishkaSlug.slugify("Straße Öl", language: "de")
#=> {:ok, "strasse-oel"}

MishkaSlug.slugify("Ærø", language: "da")
#=> {:ok, "aeroe"}

Arabic is left alone. The Turkish rule shows only when you keep the Latin letters as typed:

elixir
MishkaSlug.slugify("ISPARTA", language: "tr", latin: :keep)
#=> {:ok, "ısparta"}

MishkaSlug.slugify("ISPARTA", latin: :keep)
#=> {:ok, "isparta"}

List the languages of the site

Pass locales: with the codes of the languages your site publishes in. Only the letters and digits of their scripts, and Latin, are kept. Latin is always allowed, because brand names and English words appear in every language.

elixir
MishkaSlug.slugify("Привет мир Hello", locales: ["en"])
#=> {:ok, "hello"}

MishkaSlug.slugify("آموزش React در ۱۰ دقیقه", locales: ["fa", "en"])
#=> {:ok, "آموزش-react-در-۱۰-دقیقه"}

An empty list, which is the default, keeps every script.

Choose a script with a subtag

A script subtag in the code picks the script. sr-Latn is Serbian in Latin letters, so the Cyrillic word is dropped.

elixir
MishkaSlug.slugify("Zdravo Здраво", locales: ["sr-Latn"])
#=> {:ok, "zdravo"}

Without a subtag, the built-in table decides. It knows 88 language codes. For any other code, see Add a language with a script resolver.

Fold Arabic letters without a language

When you pass locales: but no language:, a Persian-family locale (fa, ur or ckb) turns the Persian fold on, unless the list also holds ar.

elixir
MishkaSlug.slugify("كتاب يك", locales: ["fa"])
#=> {:ok, "کتاب-یک"}

MishkaSlug.slugify("كتاب يك", locales: ["fa", "ar"])
#=> {:ok, "كتاب-يك"}

Handle digits of other scripts

A digit follows the script rule like a letter. With locales: ["en"], the Persian digits in سال ۱۴۰۳ are dropped, and nothing is left. Set digits: :ascii to write them as 0-9 first, so they stay.

elixir
MishkaSlug.slugify("سال ۱۴۰۳", locales: ["en"])
#=> {:error, :no_allowed_script}

MishkaSlug.slugify("سال ۱۴۰۳", locales: ["en"], digits: :ascii)
#=> {:ok, "1403"}

Check an unknown language

A code that neither the table nor a resolver knows is an error, not a silent skip.

elixir
MishkaSlug.slugify("Сәлам", locales: ["tt"])
#=> {:error, {:unknown_locale, "tt"}}

Next steps