speakingurl

speakingurl is a dependency-free JavaScript library that converts arbitrary strings into clean, URL-safe slugs — the kind used for permalinks, semantic URLs, and “pretty” paths. Its core strength is transliteration: rather than stripping accented or non-Latin characters, it maps them to readable ASCII equivalents (e.g. “ö” to “oe” in German, or Cyrillic and Arabic script to Latin phonetic approximations), so slugs stay meaningful across more than 30 languages.

The library exposes two functions, getSlug(input, options) for one-off conversions and createSlug(options) for a pre-configured, reusable slugifier, with options covering separators, casing, truncation, RFC 3986 URI-character allowances, and custom character/word substitution maps. It runs unmodified in Node, in the browser, or via CommonJS/AMD/global exports, and ships a Ruby on Rails gem wrapper for use outside the JavaScript ecosystem.

What You Get

• getSlug(input, options) — converts a string to a slug in a single call, with sensible English defaults
• createSlug(options) — returns a pre-configured slugify function for reuse with the same settings across a codebase
• Language-aware transliteration tables for 30+ languages (German, Arabic, Russian/Cyrillic, Greek, Vietnamese, Burmese, Dhivehi, Georgian, Persian, and more)
• Fine-grained options: custom separator, maintainCase, titleCase (with word exclusions), truncate with word-boundary awareness, and custom character/word replacement maps
• RFC 3986 URI-character modes (uric, uricNoSlash, mark) for allowing reserved/mark characters in the output slug
• Works everywhere: CommonJS (Node), AMD, and browser globals, plus a bundled Ruby on Rails gem (speakingurl-rails)

Common Use Cases

• Generating permalink slugs for blog posts, articles, or CMS pages from user-entered titles
• Building SEO-friendly product or category URLs in an e-commerce catalog
• Normalizing user-generated content (usernames, tags, filenames) into URL-safe identifiers
• Producing multilingual slugs for internationalized sites where titles contain accented or non-Latin characters
• Sanitizing arbitrary strings before using them as anchor IDs, hash fragments, or file names

Under The Hood

Architecture speakingurl is a single-file UMD module (lib/speakingurl.js) with no internal layering: a module-scoped charMap object holds transliteration mappings for 30+ languages, and getSlug(input, opts) runs the input through a linear pipeline — apply language-specific symbol replacements, walk the string character-by-character through charMap (falling back to the input char when unmapped), strip disallowed characters based on the uric/uricNoSlash/mark flags, collapse whitespace/separators, then optionally truncate at a word boundary and apply case transforms. createSlug(opts) is a thin curry over getSlug returning a preconfigured closure. The export block at the bottom detects CommonJS, AMD, or browser-global environments and attaches accordingly, so the same file runs unmodified everywhere with no bundler required.

Tech Stack Plain ES5 JavaScript with zero runtime dependencies ("dependencies": {} in package.json) — the design goal stated in the README (“no dependencies!”) holds throughout. The dev toolchain is dated: Gulp 3 drives linting (JSHint), minification (uglify), version bumping, and release tagging; tests run via Mocha 3 with the should assertion library. The repo also ships a speakingurl-rails RubyGem wrapper and Bower/Component manifests, reflecting its age and its original multi-package-manager distribution strategy (npm, Bower, Component, CDN builds via cdnjs/jsDelivr).

Code Quality Test coverage is broad in scope — over 20 test files under test/ exercise defaults, separators, truncation, title-case, custom maps, and dedicated per-language suites (Arabic, Burmese, Cyrillic, Dhivehi, Georgian, Hungarian, Persian, Turkish) — but the code itself has no type annotations, TypeScript, or JSDoc-enforced contracts beyond descriptive comments, and there is no CI badge configuration active in the current repo snapshot (Travis config exists but the project shows no recent commits). Naming is consistent and functions are small, but error handling is minimal — invalid options are largely ignored rather than validated.

What Makes It Unique Unlike slugify libraries that simply strip non-ASCII characters, speakingurl’s differentiator is its breadth of language-aware transliteration — mapping accented Latin, Cyrillic, Greek, Arabic, Persian, Burmese, Dhivehi, and Georgian scripts to phonetically reasonable ASCII rather than discarding them, plus RFC 3986-aware character-allowance modes (uric, uricNoSlash, mark) that most competing slugify packages don’t expose. The trade-off is that the project has seen no meaningful maintenance since 2017 despite continued high download volume, so it functions today as a stable but effectively frozen utility.