How to use Transliteration to convert and check names according to Latin Alphabet.

#harmonyos #transliterator #crossscriptsearch #arkts

Read the original article：How to use Transliteration to convert and check names according to Latin Alphabet.

How to use Transliteration to convert and check names according to Latin Alphabet.

Requirement Description

A developer needs this to make search and matching work naturally across different scripts. For example, if an app shows city names in Chinese (“北京”), Turkish (“İzmir”), or Spanish (“Málaga”), users should still find them when typing “beijing”, “izmir”, or “malaga”. The singleton transliteration manager ensures all text is converted into a consistent Latin-based form, so queries match regardless of accents, diacritics, or script. This improves usability, accuracy, and user satisfaction in multilingual wearable apps.

Background Knowledge

HarmonyOS provides i18n.Transliterator to transform scripts (e.g., Han → Latin). Normalization removes accents/tones, making search diacritic- and case-insensitive. A singleton avoids repeatedly creating transliterators, saving resources on wearables.

Implementation Steps

Create a singleton class to initialize the transliterator once (Han-Latin, fallback Any-Latin).
Add methods:
- toLatinKey → normalize text into a search key.
- equals → compare two strings cross-script.
- contains → check if text includes query cross-script.
Ensure graceful fallback if transliteration isn’t available.
Use the singleton across app features like search bars, city lists, or daily tips for consistent results.

Code Snippet / Configuration

import { i18n } from "@kit.LocalizationKit";

export class TransliterationUtil {
  private static instance: TransliterationUtil;
  private tr: i18n.Transliterator = i18n.Transliterator.getInstance('Han-Latin');

  private constructor() {
    this.init();
  }
  public static getInstance(): TransliterationUtil {
    if (!TransliterationUtil.instance) {
      TransliterationUtil.instance = new TransliterationUtil();
    }
    return TransliterationUtil.instance;
  }

  /** Try to initialize Transliterator (Han-Latin, fallback Any-Latin) */
  private init() {
    try {
      this.tr = i18n.Transliterator.getInstance('Han-Latin');
    } catch {
      this.tr = i18n.Transliterator.getInstance('Any-Latin');
    }
  }

  /** Convert string into normalized Latin key for indexing/search */
  public toLatinKey(input: string): string {
    let out = input;
    if (this.tr) {
      try { out = this.tr.transform(input); } catch { /* keep original */ }
    }
    return out
      .toLowerCase()
      .normalize('NFKD')
      .replace(/[\u0300-\u036f]/g, '') // strip accents/tones
      .replace(/[^a-z0-9]+/g, ' ')
      .trim();
  }

  /** Cross-script equality check */
  public equals(a: string, b: string): boolean {
    return this.toLatinKey(a) === this.toLatinKey(b);
  }

  /** Cross-script substring check (useful for search bars) */
  public contains(text: string, query: string): boolean {
    const q = query.trim();
    if (q.length === 0) return true;
    return this.toLatinKey(text).includes(this.toLatinKey(q));
  }
}

console.log('RESULT Convert: ' + TransliterationUtil.getInstance().toLatinKey("北京"));
console.log('RESULT Convert: ' + TransliterationUtil.getInstance().toLatinKey("İzmir"));

console.log('RESULT check: ' + TransliterationUtil.getInstance().equals("北京", "bei jing")); // true
console.log('RESULT check: ' + TransliterationUtil.getInstance().equals("İzmir", "izmir")); // true

console.log('RESULT contains: ' + TransliterationUtil.getInstance().contains("欢迎来到北京", "bei jing")); // true
console.log('RESULT contains: ' + TransliterationUtil.getInstance().contains("Málaga Essentials", "malaga")); // true