encoding.slug
A URL slug generator with built-in transliteration tables for Persian, Arabic, Cyrillic, Greek, Latin accents, Hebrew, Hindi, Thai, Japanese kana and Korean.
import encoding.slug
A slug is the readable part of an address, like my-first-post in /blog/my-first-post. This package turns a title in any language into one. It is written in Salam, uses fixed tables only (no models, no network, no files), keeps no state, and is safe to call from many threads at once.
Make is the whole story for most programs: it transliterates to ASCII, lowercases, drops emoji, spells out & and %, and joins the words with a hyphen. MakeWith takes an Options value when you need another separator, a length limit, stop words, your own replacements or native letters.
Titles to slugs in one call
Punctuation and spaces become one separator, apostrophes vanish without leaving a gap (what's is whats), accents are removed, symbols such as &, @, %, + and currency signs are written as words, and emoji are dropped.
import encoding.slug
func main:
println slug.Make("Hello, World!")
println slug.Make(" 10 Tips & Tricks for 100% Better Code ")
println slug.Make("What's new in v2.0? (Release Notes)")
println slug.Make("Café crème brûlée")
println slug.Make("user@example.com")
println slug.Make("Launch day 🚀🎉")
endMany languages, one table per script
The script of the text picks the table. DetectScript names the dominant script of a text: latin, cyrillic, greek, arabic, hebrew, devanagari, thai, japanese, korean or han, and an empty text for digits and symbols only. The tables follow the usual conventions of each language, so the result is the spelling readers expect, not a letter-by-letter code.
| Script | What is covered |
|---|---|
| Latin | Latin-1, Extended-A and B, Vietnamese, Polish, Czech, Nordic, Turkish; ß is ss, æ is ae, þ is th, full-width letters and ligatures are unfolded. With the language de, ä ö ü become ae oe ue; with da or no, å ø become aa oe. |
| Cyrillic | Russian by default, Ukrainian (г is h, и is y, ї is yi at the start of a word and i inside it), Bulgarian (ъ is a, щ is sht), Serbian and Macedonian without diacritics, Belarusian. |
| Greek | ELOT 743 style: ου is ou, μπ is b at the start of a word and mp inside it, accents and polytonic marks are removed. |
| Arabic script | Persian and Arabic, see the next section. |
| Hebrew | Consonants only (the text has no vowels), points are ignored. |
| Devanagari | Hindi: consonants carry an inherent a that is dropped at the end of a word and after a virama. |
| Thai | A basic table: consonants, vowels, pre-posed vowels moved after their consonant, tone marks ignored. |
| Japanese | Hiragana and katakana to Hepburn: きょ is kyo, っ doubles the next consonant, the long vowel mark is ignored. |
| Korean | Hangul syllables are taken apart into their letters algorithmically and written in Revised Romanization, without sound changes between syllables. |
| Chinese | No pinyin table: Han characters pass through unchanged (see keep_han). |
import encoding.slug
func show(title: str):
println slug.DetectScript(title) + ":", slug.Make(title)
end
func main:
show("Привет, мир! Щука и Ёж")
show("Київ Їжак Ґанок")
show("Ελληνικά: Καλημέρα κόσμε")
show("Ağaç ışık İstanbul şeker")
show("Zażółć gęślą jaźń Łódź")
show("Nguyễn Thị Minh Khai Đà Nẵng")
show("שלום עולם")
show("हिन्दी भारत नमस्ते")
show("สวัสดี ครับ")
show("こんにちは ラーメン")
show("안녕하세요 한국어")
show("你好 世界")
endPersian and Arabic
Persian and Arabic share a script, so the language is told apart by the letters: any of پ چ ژ گ ک ی or the digits ۰ to ۹ mean Persian; ة ى ي ك أ إ without them mean Arabic; text with neither is read as Persian. Pass lang = "fa" or "ar" to decide yourself.
- Persian digits and Arabic-Indic digits become
0to9everywhere. - Tashkeel (harakat), shadda, tatweel and the Quranic marks are removed; presentation forms (
ﻻ,ﺳ) are first turned into the plain letters. - The zero-width non-joiner is a word boundary:
میخواهمbecomesmi-khvahm. - Arabic
يandكare the same letters as Persianیandک. - Letters follow the common conventions:
خiskh,شissh,چisch,ژiszh,گisg,عisa; Persianقisghandث ذ ضares z z, Arabicقisqandث ذ ضareth dh d. وandیare guessed from their neighbours. In Persian,وisvat the start of a word or before a vowel letter,uotherwise, andvawhen it stands alone as the word "and";یisyat the start, next to a vowel letter, andiotherwise;ایat the start of a word isi(ایرانisiran). In Arabic,وisw.- Short vowels are not written in Persian or Arabic text and are not guessed, so
سلامisslamandمحمدismhmd. When the pretty English spelling matters (a person or a place), set it withAddReplacement.
import encoding.slug
func main:
println slug.Make("سلام دنیا")
println slug.Make("میخواهم ایران را ببینم")
println slug.Make("ژاله و گلی، چای شیرین")
println slug.Make("قیمت: ۱۲۳٫۵۰ ریال")
println slug.Make("كتاب علي")
println slug.Make("مَدرَسه ـــ کِتاب")
println slug.Transliterate("خوب است، دوستان!", "")
println slug.Transliterate("قطر ثلاثة", "ar")
println slug.Transliterate("قطر ثلاثة", "fa")
endOptions
Start from DefaultOptions (or a preset) and change what you need. Stop words are compared with the finished words, so write them in any script and case: they go through the same transliteration as the text. If every word of a title is a stop word, the words are kept so the slug is not empty. Replacements are plain text, applied left to right before anything else, so C++ can become cpp before the plus signs turn into words. fallback is returned when nothing is left.
import encoding.slug
func main:
title := "The Quick Brown Fox & the Lazy Dog"
println slug.Make(title)
mut opts := slug.Options {}
opts.separator = "_"
println slug.MakeWith(title, opts)
opts = slug.DefaultOptions()
opts.lowercase = false
println slug.MakeWith(title, opts)
opts = slug.DefaultOptions()
slug.AddStopWords(opts, "the a an and of")
println slug.MakeWith(title, opts)
opts = slug.DefaultOptions()
opts.symbols = false
println slug.MakeWith(title, opts)
opts.lang = "de"
opts.symbols = true
println slug.MakeWith(title, opts)
opts = slug.DefaultOptions()
slug.AddReplacement(opts, "C++", "cpp")
slug.AddReplacement(opts, "C#", "csharp")
println slug.MakeWith("C++ versus C#", opts)
opts = slug.DefaultOptions()
opts.allow = "."
println slug.MakeWith("Report v1.2.final", opts)
opts = slug.DefaultOptions()
opts.fallback = "untitled"
println slug.MakeWith("???", opts)
slug.FreeOptions(opts)
endLimiting the length
max_length counts characters, not bytes. The slug is cut between words, never in the middle of one: whole words are kept while they fit, with their separators. Only when the very first word is longer than the limit is it cut, so the result is never empty for a non-empty title. The URL preset limits slugs to 100 characters.
import encoding.slug
func main:
title := "How to build a fast and friendly web server in Salam"
mut opts := slug.Options {}
opts = slug.DefaultOptions()
println slug.Make(title)
opts.max_length = 30
println slug.MakeWith(title, opts)
opts.max_length = 12
println slug.MakeWith(title, opts)
opts.max_length = 5
println slug.MakeWith("extraordinary", opts)
println slug.MakeWith(title, slug.URL())
endKeeping the native letters
With keep_unicode the letters of every script stay as they are: only the case is folded (Latin, Greek and Cyrillic), Persian forms are unified (ي to ی, ك to ک), digits become ASCII, marks that do not belong in a word are removed and separators work as usual. Modern browsers and search engines handle such addresses, and they read better for Persian, Russian or Greek sites. Input should be in normal form NFC. Without keep_unicode, Han characters are still kept because no table exists; set keep_han to false to drop them.
import encoding.slug
func main:
mut opts := slug.Options {}
opts = slug.Unicode()
println slug.MakeWith("سلام دنیا، ۱۲۳ ك ي", opts)
println slug.MakeWith("Привет, Мир!", opts)
println slug.MakeWith("Crème Brûlée Ñandú", opts)
println slug.MakeWith("你好 世界", opts)
opts.lowercase = false
println slug.MakeWith("Привет, Мир!", opts)
opts = slug.DefaultOptions()
println slug.MakeWith("abc 你好 def", opts)
opts.keep_han = false
println slug.MakeWith("abc 你好 def", opts)
endUnique slugs
Unique takes a function that says whether a slug is already used (a database lookup, a set, a directory listing) and returns the slug itself or the first free one of slug-2, slug-3 and so on. UniqueWith picks the separator and Numbered builds one numbered name. After ten thousand tries the number reached so far is returned, so a function that always answers yes cannot hang the program.
import encoding.slug
func taken(s: str): bool:
ret s == "post" or s == "post-2" or s == "post-3"
end
func main:
println slug.Unique("fresh", (s: str): ret taken(s) end)
println slug.Unique("post", (s: str): ret taken(s) end)
println slug.UniqueWith("post", "_", (s: str): ret taken(s) end)
println slug.Numbered("post", 7, "-")
endChecking a slug
IsSlug accepts only what Make can produce with the default options: lowercase letters and digits joined by single hyphens, none at either end. IsSlugWith checks against the options you used, including the separator, the length limit and native letters.
import encoding.slug
func main:
println slug.IsSlug("hello-world")
println slug.IsSlug("Hello World")
println slug.IsSlug("-hello-")
println slug.IsSlug("a--b")
println slug.IsSlug(slug.Make("Any title, any language: Привет"))
println slug.IsSlugWith("hello_world", slug.Snake())
println slug.IsSlugWith("سلام-دنیا", slug.Unicode())
println slug.IsSlugWith("9lives", slug.Identifier())
endPresets
URL is the default with a 100 character limit. Filename keeps case, uses _, allows dots and hyphens, limits to 200 characters, never starts or ends with a dot and falls back to file, so ../etc/passwd cannot escape a directory. Snake uses _. Identifier uses _, never starts with a digit and falls back to _, which is what you want for a variable or a column name. Unicode keeps native letters.
import encoding.slug
func main:
title := "My Report: Q3 2026 (final).PDF"
println "default ", slug.Make(title)
println "url ", slug.MakeWith(title, slug.URL())
println "filename ", slug.MakeWith(title, slug.Filename())
println "snake ", slug.MakeWith(title, slug.Snake())
println "identifier", slug.MakeWith("9 lives of a cat", slug.Identifier())
println "unicode ", slug.MakeWith("Привет мир", slug.Unicode())
endWhat people get wrong:
- Expecting
slamto be writtensalam. Persian and Arabic text has no short vowels, and the package does not invent them; useAddReplacementfor names. - Using the slug as a key without
Unique. Two different titles can give the same slug, and an empty title gives an empty one unlessfallbackis set. - Counting bytes.
max_lengthcounts characters; withkeep_unicodea Persian slug of 50 characters is about 100 bytes. - Splitting
camelCase:fooBarisfoobar. Put a space in the title if you want two words. - Freeing an
Optionsthat holds stop words or replacements twice. Copies of anOptionsshare those two lists, so callFreeOptionsonce for the family.
Every string returned is new and belongs to the caller. For percent-encoding see encoding.url; to escape text for pages see encoding.html.
Types
Options
struct Options| Name | Type | Description |
|---|---|---|
separator | str = "-" | Text put between words, a hyphen by default. May be longer than one character or empty. |
lowercase | bool = true | Fold letters to lowercase. On by default. |
max_length | int = 0 | Largest length in characters, cut between words. 0 means no limit. |
lang | str = "" | Language code that picks between conventions (de, da, no, uk, bg, sr, fa, ar, ru and so on). Empty means detect it from the script. Region suffixes such as pt-BR are ignored. |
keep_unicode | bool = false | Keep the letters of every script instead of transliterating them. |
keep_han | bool = true | Keep Han characters, which have no table. On by default; when off they are dropped. |
stop_words | Vector | Words left out of the slug. Use AddStopWords to fill it. |
replacements | Vector | Pairs of pattern and value applied to the title first. Use AddReplacement to fill it. |
trim | bool = true | Remove separators, and allowed punctuation, from both ends. On by default. |
collapse | bool = true | Merge a run of separators into one. On by default; when off every character that is not kept gives its own separator. |
allow | str = "" | ASCII punctuation that stays in the slug, such as ._~ . A separator is not put next to an allowed character. |
symbols | bool = true | Spell & @ % + $ and currency signs as words. On by default; when off they are only separators. |
identifier | bool = false | Make the result usable as a name in code: when it starts with a digit an underscore is put in front. |
fallback | str = "" | Returned when the slug would be empty. |
import encoding.slug
func main:
mut opts := slug.Options {}
opts = slug.DefaultOptions()
opts.separator = "_"
opts.max_length = 20
opts.lang = "de"
slug.AddStopWords(opts, "the of")
slug.AddReplacement(opts, "&", " und ")
println slug.MakeWith("The Best of Müller & Söhne in Köln", opts)
slug.FreeOptions(opts)
println slug.MakeWith("Report (final).pdf", slug.Filename())
println slug.MakeWith("9 lives", slug.Identifier())
println slug.MakeWith("Привет мир", slug.Unicode())
println slug.MakeWith("a b c", slug.URL())
endFunctions
DetectScript
func DetectScript(text: str): strimport encoding.slug
func main:
println slug.Make("Hello, World! Ünïcödé & Co.")
println slug.MakeWith("Hello, World!", slug.Snake())
println slug.Transliterate("Привет, мир! Zürich", "")
println slug.Transliterate("Müller Größe", "de")
println slug.DetectScript("こんにちは")
println slug.DetectScript("Καλημέρα")
endDefaultOptions
func DefaultOptions(): OptionsThe example for this item is shown with the ones above: encoding-slug-Options.salam
URL
func URL(): OptionsThe example for this item is shown with the ones above: encoding-slug-Options.salam
Filename
func Filename(): OptionsThe example for this item is shown with the ones above: encoding-slug-Options.salam
Snake
func Snake(): OptionsThe example for this item is shown with the ones above: encoding-slug-Options.salam
Identifier
func Identifier(): OptionsThe example for this item is shown with the ones above: encoding-slug-Options.salam
Unicode
func Unicode(): OptionsThe example for this item is shown with the ones above: encoding-slug-Options.salam
AddStopWords
func AddStopWords(o &: Options, words: str)The example for this item is shown with the ones above: encoding-slug-Options.salam
AddReplacement
func AddReplacement(o &: Options, pattern: str, value: str)The example for this item is shown with the ones above: encoding-slug-Options.salam
FreeOptions
func FreeOptions(o &: Options)The example for this item is shown with the ones above: encoding-slug-Options.salam
MakeWith
func MakeWith(text: str, o: Options): strThe example for this item is shown with the ones above: encoding-slug-Make.salam
Make
func Make(text: str): strThe example for this item is shown with the ones above: encoding-slug-Make.salam
Transliterate
func Transliterate(text: str, lang: str): strThe example for this item is shown with the ones above: encoding-slug-Make.salam
Numbered
func Numbered(slug: str, n: int, separator: str): strimport encoding.slug
func used(s: str): bool:
ret s == "post" or s == "post-2"
end
func main:
println slug.Unique("post", (s: str): ret used(s) end)
println slug.UniqueWith("post", "_", (s: str): ret used(s) end)
println slug.Numbered("post", 5, "-")
println slug.IsSlug("post-3")
println slug.IsSlugWith("Post_3", slug.Snake())
endUniqueWith
func UniqueWith(slug: str, separator: str, exists: func(str): bool): strThe example for this item is shown with the ones above: encoding-slug-Unique.salam
Unique
func Unique(slug: str, exists: func(str): bool): strThe example for this item is shown with the ones above: encoding-slug-Unique.salam
IsSlugWith
func IsSlugWith(s: str, o: Options): boolThe example for this item is shown with the ones above: encoding-slug-Unique.salam
IsSlug
func IsSlug(s: str): boolThe example for this item is shown with the ones above: encoding-slug-Unique.salam