Language Profiles¶

Functions for querying and extending transliteration language profiles.

list_langs¶

list_langs ¶

list_langs() -> list[str]

Return available language codes for transliteration.

Returns:	`list[str]` – Sorted list of language code strings (e.g. ["ar", "bg", "de", ...]).

Raises:	`TranslitError` – If the language table lock is poisoned.

Examples:

>>> "de" in list_langs()
True
>>> "ja" in list_langs()
True

Example¶

from translit import list_langs

langs = list_langs()
print(langs)
# => ['am', 'ar', 'as', 'bg', 'bn', 'bo', 'ca', 'cs', 'cy', 'da', 'de', 'dv', 'el',
#     'es', 'et', 'fa', 'fi', 'fr', 'ga', 'gu', 'he', 'hi', 'hr', 'hu', 'hy',
#     'is', 'it', 'ja', 'jv', 'ka', 'km', 'kn', 'ko', 'lo', 'lt', 'lv', 'ml', 'mn',
#     'mr', 'mt', 'my', 'ne', 'nl', 'no', 'or', 'pa', 'pl', 'pt', 'ro', 'ru', 'sa',
#     'si', 'sk', 'sl', 'sq', 'sr', 'sv', 'ta', 'te', 'th', 'tr', 'uk', 'vi', 'zh']

Returns both built-in and user-registered language codes, sorted alphabetically.

Tip

Use lang="auto" to auto-detect the language from the dominant non-Latin script in the input, instead of specifying a code manually. See Language Support for details.

register_lang¶

register_lang ¶

register_lang(code: str, mappings: dict[str, str]) -> None

Register or override a transliteration mapping for a language code.

Parameters:	`code` (`str`) – Language code string (e.g. "xx", "custom"). `mappings` (`dict[str, str]`) – Dict of source→replacement character mappings.

Raises:	`TranslitError` – If the language table lock is poisoned or the mapping cannot be stored.

Examples:

>>> register_lang("xx", {"Ä": "Ae", "ä": "ae", "Ö": "Oe", "ö": "oe"})
>>> transliterate("Ärger", lang="xx")
'Aerger'

Example¶

from translit import register_lang, transliterate

register_lang("eo", {
    "ĉ": "cx", "ĝ": "gx", "ĥ": "hx",
    "ĵ": "jx", "ŝ": "sx", "ŭ": "ux",
})

transliterate("ĉapelo", lang="eo")  # => "cxapelo"

# Verify registration
from translit import list_langs
assert "eo" in list_langs()

Warning

This is a global, process-wide operation. Registered profiles persist for the lifetime of the Python process and are visible to all threads.

register_replacements¶

register_replacements ¶

register_replacements(replacements: dict[str, str]) -> None

Register global pre-transliteration replacements.

New entries are merged into the existing table. Existing keys are silently overwritten. Use :func:clear_replacements to wipe the table, or :func:remove_replacement to remove a single key.

Parameters:	`replacements` (`dict[str, str]`) – Dict of source→replacement string mappings, applied before the main transliteration tables.

Examples:

>>> register_replacements({"©": "(c)", "®": "(r)"})

Example¶

from translit import register_replacements, transliterate

register_replacements({
    "©": "(c)",
    "®": "(R)",
    "™": "(TM)",
})

transliterate("Hello™ World©")  # => "Hello(TM) World(c)"

Replacements are applied as a pre-processing step before the character-by-character transliteration lookup. They are global and persist for the process lifetime.

remove_replacement¶

remove_replacement ¶

remove_replacement(key: str) -> bool

Remove a single global pre-transliteration replacement by key.

Parameters:	`key` (`str`) – The source string to remove from the replacement table.

Returns:	`bool` – True if the key was present and removed, False otherwise.

Examples:

>>> register_replacements({"©": "(c)"})
>>> remove_replacement("©")
True
>>> remove_replacement("©")
False

Example¶

from translit import register_replacements, remove_replacement, transliterate

register_replacements({"©": "(c)", "®": "(R)"})
transliterate("©®")  # => "(c)(R)"

remove_replacement("©")  # => True  (was registered)
remove_replacement("©")  # => False (already removed)
transliterate("©®")      # => "(R)" — only ® replacement remains

clear_replacements¶

clear_replacements ¶

clear_replacements() -> None

Clear all global pre-transliteration replacements.

Examples:

>>> register_replacements({"©": "(c)", "®": "(r)"})
>>> clear_replacements()

Example¶

from translit import register_replacements, clear_replacements, transliterate

register_replacements({"©": "(c)", "®": "(R)"})
transliterate("©®")  # => "(c)(R)"

clear_replacements()
transliterate("©®")  # => "(c)(R)" is gone — falls back to default table

Note

clear_replacements() removes all user-registered replacements. Built-in transliteration tables are not affected.