# ascii-slugs: readable ASCII slugs from non-Latin titles

[ascii-slugs](https://github.com/IndianOpinion/ascii-slugs) is a PHP library and a thin WordPress plugin for sites that handle titles in Devanagari, Tamil, Urdu, Cyrillic and other non-Latin scripts. It turns those titles into short, readable ASCII slugs. It is MIT licensed, and v0.1.0 was released on 14 November 2026.

## The problem

When a title is not in Latin script, WordPress keeps the UTF-8 bytes of the slug and percent-encodes them. Each byte costs three characters, such as %e0, so one Devanagari code point costs nine. The slug column holds 200 bytes, and WordPress cuts the encoded slug there without a warning. In Devanagari that keeps about 22 code points, and the URL usually stops in the middle of a word. Nothing errors and nothing is logged. The broken URL is then shared, indexed and linked for good.

The README's example: a 38 code point Hindi headline needs 286 bytes once encoded, so WordPress stores a slug cut at 200 bytes. The ascii-slugs result is 49 bytes: chandrayan-mishan-ki-saphalata-par-desh-men-jashn.

Encoded slugs have other costs. Links pasted into chat or email show as long %E0%A4 strings and some tools break them. Two titles that differ only after the 22nd code point get the same cut slug plus a -2. Logs and cache keys become hard to read.

## What it does

- Transliterates with built-in tables for Devanagari, Bengali-Assamese, Gurmukhi, Gujarati, Odia, Tamil, Telugu, Kannada, Malayalam, Arabic script with Urdu rules, Cyrillic, Greek and accented Latin. It needs no intl extension.

- Falls back to a short dated hash such as post-20261112-459eae08 when a slug would be unreadable.

- Applies the library to new post and term slugs in WordPress, and leaves English titles to core.

- Audits and repairs slugs that are already encoded, through wp ascii-slugs audit and repair. Repair is a dry run unless you pass --yes.

- Adds a Site Health section that shows the count of encoded slugs and whether intl is available.

## How it works

The library lives in the namespace IndianOpinion\AsciiSlugs, has no dependencies and no WordPress code. Slugger::slug() works in five steps:

- Prepare: check UTF-8, decode HTML entities (up to three passes, for feed titles), strip tags, drop zero-width joiners and similar marks, and remove apostrophes inside words.

- Split the text into runs of one script each.

- Transliterate each run with its own table, loaded on first use. The Indic tables handle the inherent vowel, matras, virama conjuncts, anusvara, nukta letters and native digits. Scripts with no table go to ICU if intl is present, or are dropped.

- Lower-case, keep [a-z0-9] joined by single hyphens, and cut at a word boundary under maxLength (default 80).

- Apply a readability floor: at least three letters or digits, at least one letter, and at least half of the title's letters transliterated. Otherwise return {prefix}-{yyyymmdd}-{hash}.

use IndianOpinion\AsciiSlugs\Slugger;

$slugger = new Slugger();
$result = $slugger->slug('ISRO का चंद्रयान-3 मिशन');
$result->slug; // "isro-ka-chandrayan-3-mishan"
$result->method; // "transliterated"
$result->coverage; // 1.0

In WordPress, the plugin hooks sanitize_title at priority 9 and acts only in the save context, and only when core would percent-encode something. A hook on wp_unique_post_slug catches slugs that arrive already encoded and finishes with core's own uniqueness check. A hook on pre_term_slug protects existing term slugs on edit. The plugin stores nothing: no options, tables, post meta or files.

Repair builds each new slug from the stored title and saves through wp_update_post(), so core records the old slug and its old-slug redirect sends the old URL to the new one with a 301.

## Guard rails

- Kill switch: define('ASCII_SLUGS_DISABLED', true); or return false from ascii_slugs_enabled. Every hook then returns its input unchanged.

- Activating, deactivating or uninstalling changes no stored slug. Stored slugs are ASCII percent-encoded strings, so they take the fast path and never move.

- A filter that returns the wrong type is ignored. A slug from ascii_slugs_slug is cleaned again to [a-z0-9-] and maxLength. maxLength is capped at 190, so core's suffix always fits in 200 bytes.

- Repair skips pages and other hierarchical post types, because core does not redirect their old slugs. It is idempotent, works in batches, and if one post fails the rest are still repaired and the command exits with code 1.

- Logs never include the title.

## What review changed

- Term slugs moved on edit. The term edit screen sends a decoded slug back on every save, so editing a category's description changed its URL, with no redirect for terms. The new pre_term_slug guard returns the stored encoded slug when the decoded value matches.

- Repair stripped post content. WP-CLI usually runs with no user, so kses is active and would strip iframes and embeds when wp_update_post() saves the post again. Repair now lifts the kses filters for that one save and restores them.

- Site Health ran a REGEXP count over every published row, which the review measured at 36 seconds on a million rows that did not fit the buffer pool. It now does a capped index-only count first and skips the encoded count above 100,000 posts.

- strip_tags() dropped everything after a bare <, so a title containing 3<5 lost its tail. The table review also fixed জ্ঞ to give gy and Malayalam ന്റ to give nt.

## Limits and what is next

- The output is not scholarly transliteration. Long and short vowels fold together and it does not round-trip.

- There is no Hindi medial schwa deletion, so कमला gives kamala. Urdu comes out mostly as a consonant skeleton with long vowels, apart from twenty common words spelled from an exception list.

- No built-in table for Sinhala, Meetei Mayek, Ol Chiki, Tibetan, Thai, Chinese, Japanese, Korean or Hebrew. They need intl or get the hash.

- Repair moves the post's modified date to now, which is core behaviour. It does not purge caches or rebuild sitemaps. ascii_slugs_repaired is the hook for that.

- Speed misses the PRD budget of 0.5 ms for a 200 code point title. The review measured about 1.2 ms for the first slug in a request and 0.5 to 0.6 ms once the table is loaded, on a shared VM. An open issue tracks bringing the first slug under budget.

Test status: this is v0.1.0. There are 264 PHPUnit tests on PHP 8.3, the same 264 on PHP 8.1 without intl (two intl tests skipped), PHPStan level 8 and phpcs clean. The tests use stubs and mocks, not a live WordPress site, and the plugin has not run on a live site. CI has not run on GitHub yet. It was specified, built and reviewed in separate roles by language-model coding agents under the editor's direction.

## Install

It needs PHP 8.1 or later. The plugin needs WordPress 6.4 or later and no Composer at runtime.

composer require indianopinion/ascii-slugs

The package is not on Packagist yet, so add a Composer vcs repository entry for https://github.com/IndianOpinion/ascii-slugs first.

Without Composer, require bootstrap.php for the library, or copy the ascii-slugs folder to wp-content/plugins/ and activate it.

[All 47 utilities](https://indianopinion.org/blog/open-source/) · [ascii-slugs on GitHub](https://github.com/IndianOpinion/ascii-slugs)

Canonical: https://indianopinion.org/blog/open-source/ascii-slugs/

AI disclosure: Every summary and comment here is written by AI and published automatically, without a person reviewing each article. We do no original reporting. How this works: https://indianopinion.org/ai-use-policy/
