=== Robse Auto Alpha Slug ===
Contributors: robsejp
Tags: slug, permalink, japanese, romaji, seo
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Turns Japanese post titles into clean ASCII slugs, and never invents a wrong reading for the kanji it cannot read.

== Description ==

Publish a post titled お知らせ in WordPress and the permalink becomes
`/%e3%81%8a%e7%9f%a5%e3%82%89%e3%81%9b/`. It works, but it is unreadable in a
browser bar, it breaks when pasted into chat, and it is useless in a report.
The usual fix is to type an English slug by hand for every single post, and the
usual result is that somebody forgets.

Robse Auto Alpha Slug fills the slug in for you when you save. Kana are romanized, so
おしらせ becomes `oshirase` and デイサービス becomes `deisabisu`. A slug you
typed yourself in plain ASCII is always left alone.

= Kanji are handled honestly =

This is where other plugins quietly go wrong. PHP has no reliable way to read
kanji: the ICU transliterator that most plugins call reads them **as Chinese**,
so 村松 comes out as `cun-song` and 出雲そば as `chu-yunsoba`. That is not a
slug anybody wants, and it is worse than no slug at all because it looks
deliberate.

So this plugin does not guess. When a title contains kanji it cannot resolve,
it uses a predictable pattern instead — `post-123` by default — and leaves the
guessing to you:

* **Fallback (default).** A clean, predictable slug such as `post-123`.
* **Drop the kanji.** Build the slug from the kana and Latin text that remain.
* **Transliterate.** The ICU behaviour described above. Correct for Chinese
  sites, wrong for Japanese ones, and labelled as such in the settings.

= A dictionary for the words you actually use =

Company names, place names and people's names come up again and again on one
site. Teach them once:

`
出雲 = izumo
美食旅 = gourmet-trip
村松英俊 = muramatsu-hidetoshi
`

Now 出雲そば 美食旅 becomes `izumo-soba-gourmet-trip` instead of falling back.
Longer terms win over shorter ones, so 出雲市 can differ from 出雲.

= No intl extension required =

The kana table is built into the plugin, so romanization works the same on a
server without the intl extension. Sokuon and youon are handled: まっちゃ
becomes `matcha`, ぎゅうにゅう becomes `gyuunyuu`.

= Everything else =

* Choose which post types are handled, or let the plugin detect them.
* Cap the slug length, cut on a word boundary.
* Try a title on the settings screen and see the slug before you publish
  anything.
* Decide whether percent-encoded slugs are replaced or left as they are.

== Installation ==

1. Install and activate the plugin.
2. That is enough for kana titles. Nothing else is required.
3. To change how kanji are handled, or to add dictionary entries, go to
   **Settings → Robse Auto Alpha Slug**.

Existing posts are never touched. Only posts you save after activating get a
generated slug, so your current permalinks and their search rankings stay as
they are.

== Frequently Asked Questions ==

= Will it overwrite a slug I typed myself? =

No. A slug written in ASCII letters, digits, hyphens or underscores is treated
as deliberate and kept, whatever the title says.

= Will it change the slugs of my existing posts? =

Not on its own. Slugs are only generated when a post is saved. If you open an
old post with a percent-encoded slug and save it, the slug is replaced — turn
off **Replace slugs that arrive percent-encoded** in the settings if you would
rather that never happened.

= Why does my kanji title become post-123 instead of romaji? =

Because a wrong reading is worse than no reading. See the description above.
Add the words to the dictionary, or switch the mode to **Drop the kanji**, and
you will get a text slug.

= Does it work with custom post types? =

Yes. By default every post type with an editing screen is handled. You can
restrict that on the settings page, or with the `robse_auto_alpha_slug_post_types`
filter.

= Can I change the generated slug from my own code? =

Yes, filter `robse_auto_alpha_slug_generated`:

`
add_filter( 'robse_auto_alpha_slug_generated', function ( $slug, $title, $post_type, $post_id ) {
    return 'news-' . $slug;
}, 10, 4 );
`

== Changelog ==

= 2.0.0 =
* Kanji are no longer transliterated as Chinese by default. Titles containing
  kanji now use a predictable fallback pattern, and the old behaviour is still
  available as an option.
* Added a settings screen: kanji handling, fallback pattern, dictionary, post
  types, maximum length, and a preview field.
* Added a user dictionary so recurring names and places romanize correctly.
* Kana romanization no longer depends on the intl extension.
* Fixed ヴァイオリン and similar katakana producing stray characters in slugs.
* Renamed internal classes and hooks to a unique prefix. The old
  `rm_auto_alpha_slug_post_types` filter still works.

= 1.6.0 =
* Kept manually entered ASCII slugs untouched.

= 1.0.0 =
* First release, distributed from robse.jp.

== Upgrade Notice ==

= 2.0.0 =
Kanji titles no longer produce Chinese readings. If you relied on that
behaviour, choose "Transliterate with the intl extension" on the settings
screen after updating. Existing slugs are not changed.
