Add ICU Transliteration Aliases Without Replacing Search Identity

Direct answer

A transliteration search key is a derived alias, not a replacement for the source text. It can help a query written in one script find a record stored in another, but the mapping may be lossy or ambiguous. Keep the original display string and stable record ID authoritative, and store each derived key with its transform ID, ICU/runtime version, source revision, and generation status. A search hit on an alias should return the original record and identify that the match came from a derived key. Do not use the alias as an identity key, permission token, deduplication rule, or evidence that two people or records are the same. Android's platform ICU Transliterator performs character transformation; it does not translate the meaning of words or sentences. The Android API surface for android.icu.text.Transliterator is documented from API 29. Call getAvailableIDs() or instantiate the exact runtime ID and handle an unavailable ID; record the Android/ICU data environment. If a standalone ICU4J dependency is chosen instead, pin that artifact and data version separately. Never guess that a convenient script-to-Latin transform name is available or identical on every device. Normalization and transliteration solve different identity problems. NFC/NFD address canonical Unicode equivalence; NFKC/NFKD also fold some compatibility distinctions. Case folding is separate again. None is a general script-to-Latin transliteration, and compatibility normalization can erase distinctions in names or identifiers. ICU offers normalization and script transforms, but their order and filters change the key. Preserve original code points, version each stage, and test only a product-defined pipeline. Do not strip every mark or punctuation as generic cleanup. Do not assume reverse transforms are exact. ICU's user guide explains that inverse mappings are not guaranteed to recover the original in every direction; script transliteration may produce collisions. Its Greek example illustrates how distinct source sequences can map to the same Latin result. A query alias can therefore match multiple records. Keep a one-to-many mapping from normalized alias to stable record IDs, display the original strings, and ask the user to disambiguate rather than collapsing records or selecting the first match. A similarity or alias match can broaden retrieval; it cannot authorize opening, exporting, or modifying a record. Treat alias generation as part of the search index lifecycle. Generate keys from committed full strings, not an unfinished incremental transliteration buffer. Store transform ID, pipeline order, ICU/dependency version, and source revision with each alias. On a transform/data upgrade, build a candidate alias set, compare collisions and fixtures, then switch under the app's migration rules. Delete aliases with their source; tombstones and queued rebuilds must not restore stale keys. Query and index pipelines must match or the alias index needs rebuilding. Keep raw query text separate and recheck access to each source row. Generated aliases can expose personal information just as source names can. Do not place transliterated names in analytics or logs merely because they use Latin characters. Retain the smallest alias set needed for the documented search task, apply the source's retention/deletion policy, and avoid exporting aliases unless the user specifically asks. Report when a transform was unavailable, when a collision exists, and when only exact source-script matching was tested. ICU language/script tables and rule versions can evolve; a result from one Android system image is not proof of identical output on a different OS build. Build a reviewed synthetic fixture corpus for every transform actually shipped: canonical equivalents, combining marks, case variants, punctuation, scripts with multiple romanization conventions, ambiguous sequences, empty output, unsupported characters, and two distinct source strings that collide. Record original text, code points, transform ID/version, alias, source record IDs, collision group, and query result. Test exact-source search independently from alias search, rebuild and deletion paths, and permissions on matched rows. This is a method for an optional search-key layer, not an OCR, translation-quality, universal romanization, or Cove feature claim.

A search query uses Latin letters for a record in another script

A local catalog stores a user-provided name in its original script. The search box accepts a romanized query, and the selected Android system ICU may produce the same Latin alias for more than one source string.

Decision

Generate a versioned secondary alias while preserving the canonical record and original text. Return all authorized collision matches for review; never merge or select a record based only on romanization.

Expected outcome

The user can find possible records through a tested alias while the app retains source spelling, provenance, and an explicit ambiguity state.

Evidence to collect

The claim becomes reviewable only when the following evidence is attached to the same artifact and test run:

• Android/ICU runtime and exact transform ID
• Original-to-alias provenance and collision fixtures
• Versioned rebuild, access recheck, and deletion behavior

Task quality needs a versioned corpus and acceptance rules. Fluent sample output is not an accuracy result.

Implementation workflow

1. Keep source identity and display text authoritative. Assign each source row a stable ID and retain its exact original string and script. Treat aliases as optional indexed fields, never as replacement display text or a primary key.
2. Pin an available ICU transform. On Android API 29+, call getAvailableIDs() or instantiate the exact Transliterator ID at runtime and record ICU/data version. If unavailable, retain exact-script search and report that alias generation is unsupported.
3. Version normalization, case-folding, and transliteration. Declare NFC/NFD or compatibility normalization, case folding, and script transform as separate stages with a fixed order and filters. Do not remove marks or punctuation unless the search contract requires it.
4. Preserve collisions and match provenance. Map each alias to all source record IDs, retain transform/version and source revision, and show original values when results collide. Never use an alias match as identity, authorization, or a merge decision.
5. Rebuild and delete derived aliases safely. Generate aliases from complete field values after transform/data changes, compare outputs and collision sets, then switch under the actual migration path. Remove aliases with the source and prevent queued work from restoring stale keys.
6. Test exact and alias search separately. Use synthetic reviewed inputs covering combining sequences, variants, collisions, unsupported characters, and transform upgrades. Recheck current source access for every result and keep raw names out of ordinary logs.

Keep each transition observable. A failure should identify the stage, artifact, runtime, and recovery action without logging private user content.

Acceptance criteria

• Original text, stable record ID, transliteration alias, normalization stage, transform ID/version, and source revision remain separately identifiable.
• The exact transform is enumerated or instantiated in the actual runtime; unavailable IDs remain unsupported instead of being guessed or silently replaced.
• Many-to-one aliases preserve every authorized source match and never merge records, replace display text, or authorize an action.
• Alias updates and deletion are bound to the source/index lifecycle; rebuilding cannot revive aliases for deleted or unauthorized records.
• The article does not call normalization transliteration, alias matches translation, or claim universal ICU output or Cove search integration.

Decision table

Failure patterns to prevent

• Replacing display text or stable IDs with aliases
• Assuming inverse transforms round-trip or aliases are unique
• Calling normalization transliteration or transliteration translation

Also prevent silent fallback, unpinned artifacts, missing cancellation, and conclusions that combine unlike configurations. Store unsuccessful runs alongside successful ones.

Minimum reproducibility record

Release checklist

• ☐ The primary query is answered without an unsupported number.
• ☐ Every artifact and runtime is pinned.
• ☐ The representative task and failure policy are explicit.
• ☐ Lifecycle, cancellation, cleanup, and fallback are tested.
• ☐ User-content and network boundaries are documented.
• ☐ Result wording applies only to the recorded configuration.
• ☐ The page links to raw method or evidence when results are added.

Sources and related evidence

• Cove benchmark method
• Android API — android.icu.text.Transliterator
• ICU User Guide — Transforms and transliteration behavior
• Unicode Standard Annex #15 — Unicode Normalization Forms

Chinese deployment and troubleshooting content is organized in the .奇连 AI 端侧专题.

Frequently asked questions