scriptconv 0.0.4a26__tar.gz → 0.0.4a28__tar.gz

{scriptconv-0.0.4a26/scriptconv.egg-info → scriptconv-0.0.4a28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scriptconv
-Version: 0.0.4a26
+Version: 0.0.4a28
 Summary: Zero-dependency script & phoneme-notation core — ISO-15924 detection & metadata, IPA↔ARPABET/X-SAMPA/Lexique/Kirshenbaum/Cotovía/RFE, Buckwalter↔Arabic, Hangul→jamo, kana
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/TigreGotico/scriptconv

{scriptconv-0.0.4a26 → scriptconv-0.0.4a28}/scriptconv/phonemizers/_vendored/__init__.py

@@ -9,8 +9,9 @@ distributed under ITS OWN license, stated in its directory:
 * ``kog2p/`` — Korean G2P (github.com/scarletcho/KoG2P), **GPL-3.0**.
   See ``kog2p/LICENSE.md``.
 * ``africa_g2p/`` — African-language G2P (github.com/AfriSpeech/africa-g2p),
-  400+ ISO 639-3 rule files. Vendored (not depended on) because it is not
-  published to PyPI and this project does not take ``git+`` dependencies.
+  400 ISO 639-3 rule files, pinned at release ``v0.2.4`` (commit e3642dea).
+  It was vendored when it was not yet on PyPI; it is now published there as
+  ``africa-g2p``, but the vendored copy is kept so the backend has no extra.
   Its **code** is Apache-2.0 — same license as the rest of this repository,
   unlike the other two entries here — but its **data** (the ``languages/``
   rule files and ``data/registry.json``) is derived from Omniglot script

scriptconv-0.0.4a28/scriptconv/phonemizers/_vendored/africa_g2p/LICENSE.md

@@ -0,0 +1,31 @@
+# Third-party license notice — africa-g2p
+
+Vendored from https://github.com/AfriSpeech/africa-g2p at tag `v0.2.4`
+(commit e3642dea), the release published to PyPI as `africa-g2p` 0.2.4.
+Every file except this one is byte-identical to `src/africa_g2p/` at that
+commit (the `data/*.json.survey` build artefact is not copied: nothing
+reads it at runtime). The **code**
+(`g2p.py`, `loader.py`, `normalizer.py`, `pipeline.py`, `cli.py`,
+`convert.py`, `english.py`, `fallback.py`, `__init__.py`) is
+**Apache-2.0**, same as the rest of this repository —
+unlike `mantoq/` and `kog2p/`, this subpackage's code carries no extra
+restriction beyond scriptconv's own license.
+
+The **data** under `languages/` and `data/registry.json` is NOT
+Apache-2.0: it is derived from third-party sources (Omniglot script
+charts, © Simon Ager; Hartell 1993/UNESCO's *Alphabets of Africa*) and
+carries its own attribution requirements — see `DATA_LICENSE.md` in this
+directory. Redistributing the language data must keep those
+attributions.
+
+`data/ipa_universal_graphemes.json` is not chart data: upstream built it
+from a survey of the rule tables and curated it with an LLM (upstream
+commit 4784edd, "Curate universal graphemes via Gemini"). Only the
+cross-language converter (`convert.py`, `convert_to_ipa`) reads it. The
+per-language pipeline that scriptconv's `AfricaG2PPhonemizer` calls
+(`AfricaPipeline`) does not.
+
+Upstream `master` after `v0.2.4` adds 238 rule tables marked
+`"confidence": "llm-draft"` (drafted by an LLM from corpus statistics).
+They are not vendored here: this copy carries only the 400 chart-sourced
+tables of the release.

scriptconv-0.0.4a28/scriptconv/phonemizers/_vendored/africa_g2p/__init__.py

@@ -0,0 +1,33 @@
+"""africa-g2p: rule-based grapheme-to-phoneme conversion for African languages."""
+from .convert import GraphemeConverter, UNIVERSAL, convert_lang, convert_to_ipa
+from .english import ENGLISH_CODES, EnglishG2P, EspeakUnavailable
+from .g2p import G2P, g2p
+from .pipeline import AfricaPipeline
+from .loader import available_languages, registry, LanguageNotFoundError
+
+# Single-sourced from the installed package metadata so it cannot drift from
+# pyproject.toml again: this constant sat at 0.1.0 through the 0.1.1 and 0.2.0
+# releases, and anything recording it — a dataset card, a provenance log — wrote
+# down the wrong version.
+try:  # pragma: no cover - trivial
+    from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+    __version__ = _pkg_version("africa-g2p")
+except Exception:  # not installed (running from a source checkout)
+    __version__ = "0.2.0"
+
+__all__ = [
+    "AfricaPipeline",
+    "G2P",
+    "g2p",
+    "GraphemeConverter",
+    "convert_lang",
+    "convert_to_ipa",
+    "UNIVERSAL",
+    "EnglishG2P",
+    "EspeakUnavailable",
+    "ENGLISH_CODES",
+    "available_languages",
+    "registry",
+    "LanguageNotFoundError",
+]

scriptconv-0.0.4a28/scriptconv/phonemizers/_vendored/africa_g2p/cli.py

@@ -0,0 +1,61 @@
+"""Command-line interface: ``africa-g2p <lang> "text"`` or ``--list``.
+
+Cross-language conversion: ``africa-g2p twi "Onyankopɔn" --to ewe`` rewrites Twi's
+graphemes in Ewe's; ``--to universal`` uses the majority grapheme for each phoneme.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .convert import GraphemeConverter, UNIVERSAL, convert_lang, convert_to_ipa
+from .g2p import G2P
+from .loader import available_languages, registry, LanguageNotFoundError
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="africa-g2p", description=__doc__)
+    parser.add_argument("lang", nargs="?", help="ISO 639-3 language code")
+    parser.add_argument("text", nargs="?", help="text to convert (or read stdin)")
+    parser.add_argument("--sep", default=None,
+                        help="separator between phoneme units (default: \" \" for G2P, "
+                             "none for --to, i.e. words are kept whole)")
+    parser.add_argument("--to", default=None,
+                        help=f"rewrite graphemes into this language (or '{UNIVERSAL}') "
+                             "instead of native output")
+    parser.add_argument("--ipa", action="store_true",
+                        help="print IPA via the universal pipeline "
+                             "(graphemes -> universal -> IPA, the g2u2p route)")
+    parser.add_argument("--list", action="store_true", help="list available languages")
+    args = parser.parse_args(argv)
+
+    if args.list or not args.lang:
+        reg = registry()
+        for code in available_languages():
+            name = reg.get(code, {}).get("name", "")
+            print(f"{code}\t{name}")
+        return 0
+
+    text = args.text if args.text is not None else sys.stdin.read()
+    if args.ipa:
+        print(convert_to_ipa(text, args.lang, sep=args.sep or " "))
+        return 0
+    if args.to:
+        try:
+            conv = GraphemeConverter(args.lang, args.to)
+        except LanguageNotFoundError as e:
+            print(e, file=sys.stderr)
+            return 1
+    else:
+        try:
+            conv = G2P(args.lang)
+        except LanguageNotFoundError as e:
+            print(e, file=sys.stderr)
+            return 1
+    sep = args.sep if args.sep is not None else ("" if args.to else " ")
+    print(conv.convert(text, sep=sep))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scriptconv-0.0.4a28/scriptconv/phonemizers/_vendored/africa_g2p/convert.py

@@ -0,0 +1,433 @@
+"""Cross-language grapheme converter.
+
+Takes the native-orthography graphemes of one language and rewrites them in the
+graphemes another language uses for the same phonemes, routing both through IPA:
+
+    L1 graphemes -> IPA -> L2 graphemes
+
+Either side may be the virtual language ``"universal"`` — the per-IPA grapheme set distilling
+    all 400 language charts: majority winners of ``scripts/ipa_universal_graphemes.py``, re-judged
+    per IPA by Gemini into common Latin/English spellings (see
+    ``scripts/build_universal_from_gemini.py``). When a source phoneme has no entry in the target's
+    chart, the universal grapheme is used as a fallback.
+
+    >>> from africa_g2p import GraphemeConverter
+    >>> GraphemeConverter("twi", "ewe").convert("Onyankopɔn")      # text, words kept
+    >>> GraphemeConverter("twi", "universal").convert("Onyankopɔn", sep=" ")  # units
+"""
+from __future__ import annotations
+
+import json
+import warnings
+import re
+import unicodedata
+from pathlib import Path
+from typing import Dict, Tuple
+
+from .g2p import G2P
+from .loader import load_rules
+from .normalizer import normalize_text, tie_affricates, tokenize
+
+_DATA = Path(__file__).resolve().parent / "data"
+_UNIVERSAL_FILE = _DATA / "ipa_universal_graphemes.json"
+
+# Virtual language code: "write every phoneme with the grapheme most languages use".
+UNIVERSAL = "universal"
+
+_universal_forward: Dict[str, str] = {}
+_universal_reverse: Dict[str, str] = {}
+_universal_g2p: "G2P | None" = None
+_reverse_cache: Dict[str, Dict[str, str]] = {}
+
+# IPA aspiration marks: modifier small-h U+02B0 (ʰ) and breathy-voiced hook U+02B1 (ʱ).
+# Dropped to relax an aspirated phoneme onto its plain counterpart for matching.
+_ASPIRATION_TRANS = str.maketrans({"\u02b0": "", "\u02b1": ""})
+
+
+def _relax_aspiration(ipa: str) -> str:
+    """Drop aspiration/breathy marks: /tɕʰ/ -> /tɕ/, /kʰ/ -> /k/, /ɡʱ/ -> /ɡ/."""
+    return ipa.translate(_ASPIRATION_TRANS)
+
+
+# --- single-phoneme filter for the universal *forward* ("reading") table ---------
+# The per-IPA grapheme picks include transliterations of multi-phoneme fidel
+# syllables (e.g. /k͡p a/ as "kpa", /ɓ i/ as "bi"). Those are fine for writing
+# (reverse table: IPA -> pick verbatim) but must not become graphemes of the
+# virtual universal orthography (forward table) — the greedy tokenizer would
+# otherwise slice ordinary words like "kpako" into "kpa"+"ko". A value counts as
+# one phoneme segment iff it has at most two core letters, and for two they form
+# a coarticulated CONSONANT pair (k͡p, t͡ʃ, ᵑɡ͡b, ts, ny ...), not C+V.
+_VOWELS = set("aàáãäæèéêëɛəɐɑɒɔɜɞɘɚeẽiĩɪɨɤɵoõöòóôuùũüʊʉɯʏøœyỹʌǝǐịụ")
+# When two different phonemes land on the same target vowel, the earlier one is
+# rewritten to a near neighbour so the pair stays distinguishable. For a real
+# language target the neighbour may be any vowel that language writes; for the
+# universal orthography it has to be a plain letter, and "a" -> "ə" was putting a
+# schwa into output that is supposed to be a-z only ("náań" -> "nəan").
+_UNIVERSAL_VOWEL_ALTERNATIVES = {"o": "u", "u": "o", "e": "i", "i": "e",
+                                 "ɔ": "u", "ɛ": "i", "a": "e", "ə": "a"}
+
+_VOWEL_ALTERNATIVES = {
+    "o": "u",
+    "u": "o",
+    "e": "i",
+    "i": "e",
+    "ɔ": "u",
+    "ɛ": "i",
+    "a": "ə",
+    "ə": "a",
+}
+
+try:
+    from spellchecker import SpellChecker
+    _spell = SpellChecker()
+except ImportError:
+    _spell = None
+
+
+def _is_english_word(word: str) -> bool:
+    if _spell is None or len(word) < 3:
+        return False
+    if not word.isalpha() or not word.isascii():
+        return False
+    return word.lower() in _spell
+_SKIP_CATEGORIES = frozenset(("Mn", "Lm", "Cn", "Pc", "Pe", "Pf", "Po", "Ps", "Sm"))
+_TIE_SPLIT = re.compile("[\u0361\u035C]")
+
+
+def _phone_cores(ipa: str) -> list:
+    """Base (consonant/vowel) letters of an IPA value, tie bars and all diacritic
+    marks, aspiration/glide/length modifiers and superscript prenasals removed."""
+    s = tie_affricates(ipa)
+    s = "".join(ch for ch in s if unicodedata.category(ch) not in _SKIP_CATEGORIES)
+    return [
+        ch
+        for part in _TIE_SPLIT.split(s)
+        for ch in part
+        if unicodedata.category(ch) in ("Ll", "Lo")
+    ]
+
+
+def _is_single_phoneme(ipa: str) -> bool:
+    cores = _phone_cores(ipa)
+    if len(cores) > 2:
+        return False
+    if len(cores) < 2:
+        return True
+    return cores[0] not in _VOWELS and cores[1] not in _VOWELS
+
+
+def _readable_grapheme(g: str) -> bool:
+    """A reading grapheme of the universal orthography must not start with a vowel
+    followed by a consonant letter. Gemini transliterates nasal vowels as <Vn>
+    ("an", "on", "in"...) — fine for writing, but as reading keys they would swallow
+    ordinary word-initial segments ("onyankopon" -> /õ.../). Vowel digraphs ("aa",
+    "ei") stay: they only match genuinely adjacent vowels."""
+    if len(g) < 2 or g[0] not in _VOWELS:
+        return True
+    return not any(ch not in _VOWELS for ch in g[1:])
+
+
+# The universal orthography is plain a-z letters, enforced in the data file itself
+# (see meta.revision there). Apostrophes marking ejectives, punctuation, placeholder
+# tokens and non-Latin script winners were all removed at the source, because a
+# speech synthesiser reads them as pauses or skips them: Xhosa "ukuba nikwazi
+# ukucalula" used to be written "uk'uba nik'wazi uk'ucalula".
+#
+# Nothing rewrites graphemes at load time any more. What remains is a guard: if the
+# table ever ships a grapheme that is not plain letters again, callers are told
+# rather than finding out from the audio.
+_PLACEHOLDER_GRAPHEMES = {"VV", "V", "C", "CC"}
+# Phonemes the universal orthography deliberately does not write.
+_UNWRITTEN = {"∅", "ʔ∅", "ʔ", "ː"}
+
+
+def _strip_combining(text: str) -> str:
+    """Reduce a phoneme to its base letters for a last-resort lookup.
+
+    Drops combining marks and the modifier letters and symbols that ride on a
+    phoneme — tone bars (˥ ˦ ˧), pharyngealisation (ˤ), velarisation (ˠ) — none of
+    which the universal orthography writes:
+
+        "ɔ́" -> "ɔ"    "h̃" -> "h"    "ɔ˥" -> "ɔ"    "əˤ" -> "ə"
+
+    Only reached when the full unit is unmapped, so a base-letter match is always
+    better than what it replaces: passing the symbol through into the text.
+    """
+    return "".join(ch for ch in unicodedata.normalize("NFD", text)
+                   if not unicodedata.combining(ch)
+                   and unicodedata.category(ch) not in ("Lm", "Sk"))
+
+
+def _is_plain_latin(grapheme: str) -> bool:
+    return bool(grapheme) and all("a" <= ch <= "z" for ch in grapheme.lower())
+
+
+def _is_usable(grapheme: str) -> bool:
+    return _is_plain_latin(grapheme) and grapheme not in _PLACEHOLDER_GRAPHEMES
+
+
+def _universal_tables() -> Tuple[Dict[str, str], Dict[str, str]]:
+    """Forward (majority grapheme -> IPA) and reverse (IPA -> majority grapheme)
+    tables for the virtual "universal" language, loaded once from the survey output."""
+    global _universal_forward, _universal_reverse
+    if not _universal_reverse:
+        data = json.loads(_UNIVERSAL_FILE.read_text(encoding="utf-8"))
+        # Build forward with the most-widespread phoneme winning on grapheme collisions
+        # (two phonemes whose majority grapheme is the same string, e.g. 'j' for d͡ʒ
+        # and ɟ), so `setdefault` keeps the commonest reading. IPA keys and values are
+        # tie-affricate-normalised to match the forward engine's output exactly.
+        order = sorted(data["phonemes"].items(), key=lambda kv: -kv[1]["langs"])
+        for raw_ipa, v in order:
+            ipa = tie_affricates(raw_ipa)
+            grapheme = v["grapheme"]
+            # An empty grapheme is deliberate, not missing: the glottal stop and the
+            # null phoneme are written as nothing. They must still enter the reverse
+            # table, or the phoneme falls through as unknown and the raw IPA symbol
+            # lands in the text ("dunmanʔn"). Nothing enters the forward table — an
+            # empty string is not readable back.
+            if grapheme:
+                _universal_reverse.setdefault(ipa, grapheme)
+                if _is_single_phoneme(raw_ipa) and _readable_grapheme(grapheme):
+                    _universal_forward.setdefault(grapheme, ipa)
+            elif "grapheme_note" in v or raw_ipa in _UNWRITTEN:
+                _universal_reverse.setdefault(ipa, "")
+        _warn_non_alphabetic(_universal_reverse)
+    return _universal_forward, _universal_reverse
+
+
+def universal_non_alphabetic() -> Dict[str, str]:
+    """IPA -> universal grapheme, for every grapheme still holding a non a-z character.
+
+    The universal orthography is supposed to be plain letters. Where the survey had
+    no plain-Latin vote for a phoneme at all — the bilabial clicks of the Khoisan
+    languages are the main case — the original symbol is kept rather than
+    approximated by a letter the language does not use or dropped from the
+    transcript. Callers feeding a speech synthesiser should know which those are.
+    """
+    _, reverse = _universal_tables()
+    return {ipa: g for ipa, g in reverse.items() if g and not _is_usable(g)}
+
+
+def _warn_non_alphabetic(reverse: Dict[str, str]) -> None:
+    """Warn once that some universal graphemes are not plain letters."""
+    # An empty grapheme is a deliberate "written as nothing", not a bad spelling.
+    offenders = {ipa: g for ipa, g in reverse.items() if g and not _is_usable(g)}
+    if not offenders:
+        return
+    sample = ", ".join(f"{ipa} -> {g}" for ipa, g in list(offenders.items())[:5])
+    warnings.warn(
+        f"{len(offenders)} universal graphemes are not plain a-z letters ({sample}"
+        f"{', ...' if len(offenders) > 5 else ''}). No plain-Latin spelling was "
+        f"attested for these phonemes. Text-to-speech will usually skip them; call "
+        f"africa_g2p.convert.universal_non_alphabetic() for the full list.",
+        UserWarning,
+        stacklevel=2,
+    )
+
+
+def _universal_g2p_engine() -> G2P:
+    """G2P engine that reads the virtual universal orthography back to IPA."""
+    global _universal_g2p
+    if _universal_g2p is None:
+        forward, _ = _universal_tables()
+        _universal_g2p = G2P.from_rules({"code": UNIVERSAL, "graphemes": forward})
+    return _universal_g2p
+
+
+def _primary_grapheme(rule: dict, candidates: set) -> str:
+    """Choose the canonical written grapheme for a phoneme within one language.
+
+    Picks the first candidate to appear in the language's own `alphabet` row (the
+    orthographer's ordering), then the first in the Latin script list, then the
+    shortest, then lexicographically — so the result is deterministic and prefers the
+    language's endorsed way of writing the sound over an allophonic variant.
+    """
+    for a in rule.get("alphabet") or []:
+        if a in candidates:
+            return a
+    for a in (rule.get("scripts") or {}).get("latin") or []:
+        if a in candidates:
+            return a
+    return min(sorted(candidates), key=lambda g: (len(g), g))
+
+
+def reverse_table(lang: str) -> Dict[str, str]:
+    """IPA -> primary grapheme for a real language's chart (cached)."""
+    if lang not in _reverse_cache:
+        rules = load_rules(lang)
+        grouped: Dict[str, set] = {}
+        for g, ipa in rules.get("graphemes", {}).items():
+            # keys normalised the same way as the forward engine's IPA output
+            grouped.setdefault(tie_affricates(ipa), set()).add(g)
+        _reverse_cache[lang] = {
+            ipa: _primary_grapheme(rules, cands) for ipa, cands in grouped.items()
+        }
+    return _reverse_cache[lang]
+
+
+class GraphemeConverter:
+    """Rewrite one language's graphemes in another's, per shared phonemes."""
+
+    def __init__(self, source: str, target: str, *, relax_aspiration: bool = True):
+        """
+        Args:
+            source: ISO 639-3 code of the input language, or "universal" to read the
+                    majority grapheme set.
+            target: ISO 639-3 code of the output language, or "universal" to write
+                    every phoneme with the grapheme most languages use.
+            relax_aspiration: when a source phoneme has no writing in the target (e.g.
+                    aspirated /tʰ/ where the target only spells plain /t/), drop the
+                    aspiration mark and map the plain phoneme instead — /tɕʰ/ writes
+                    like /tɕ/, /kʰ/ like /k/. Exact target readings always win when the
+                    target does mark aspiration. Default True.
+        """
+        forward, reverse = _universal_tables()
+        self.source = source
+        self.target = target
+        self.relax_aspiration = relax_aspiration
+        # Forward engine: language graphemes -> IPA (or majority graphemes -> IPA).
+        if source == UNIVERSAL:
+            self._forward = G2P.from_rules({"code": UNIVERSAL, "graphemes": forward})
+        else:
+            self._forward = G2P(source, output="ipa")
+        # Reverse table: IPA -> target graphemes.
+        self._reverse = reverse if target == UNIVERSAL else reverse_table(target)
+        self._universal_reverse = reverse
+        # Source's own spelling per phoneme -> flag when a target differs, so a
+        # converted phoneme that lands next to the same letter can be tripled.
+        self._source_spelling = {} if source == UNIVERSAL else reverse_table(source)
+
+    def convert(self, text: str, *, sep: str = "", lower: bool = True) -> str:
+        """Convert a full text. Word boundaries (spacing and punctuation) are always
+        preserved; `sep` joins the phoneme units *within* a word — so the default
+        ``sep=""`` emits continuous text, while ``sep=" "`` prints every unit as a
+        separate token (the phoneme-sequence view)."""
+        text = normalize_text(text, lower=lower)
+        out: list = []
+        for tok in tokenize(text):
+            if not tok.is_word or _is_english_word(tok.text):
+                out.append(tok.text)
+                continue
+            units = self._forward.convert_word(tok.text, sep=" ", lower=False).split(" ")
+            out.append(sep.join(self._map_units(units)))
+        return "".join(out)
+
+    def convert_word(self, word: str, *, sep: str = "", lower: bool = True) -> str:
+        """Convert a single word (no tokenization)."""
+        if _is_english_word(word):
+            return word
+        word = normalize_text(word, lower=lower)
+        units = self._forward.convert_word(word, sep=" ", lower=False).split(" ")
+        return sep.join(self._map_units(units))
+
+    def _map_units(self, units: list) -> list:
+        """Map each phoneme to a target grapheme, replacing the existing (preceding)
+        vowel in a conversion collision (between different source phonemes) with its
+        closest alternative (e.g. o -> u) while keeping true source doubles (long
+        vowels like hyɛɛ -> hyee) and converted vowels untouched."""
+        mapped: list = []
+        prev_g, prev_ipa, run_converted = None, None, False
+        for ipa in units:
+            g, converted = self._map(ipa)
+            alternatives = (_UNIVERSAL_VOWEL_ALTERNATIVES if self.target == UNIVERSAL
+                            else _VOWEL_ALTERNATIVES)
+            if converted and len(g) >= 2 and len(set(g)) == 1 and g[0] in _VOWELS:
+                alt = alternatives.get(g[0], "u" if g[0] in "oɔ" else "i")
+                g = alt + g[0]
+            # Only collide if it's the same target grapheme AND different source phonemes
+            # (so true source doubles like hyɛɛ -> hyee are left as double ee, not ii/etc.)
+            is_different_phoneme_collision = (g == prev_g and ipa != prev_ipa)
+            if is_different_phoneme_collision and g and g[0] in _VOWELS:
+                if mapped and mapped[-1] and mapped[-1][-1] in _VOWELS:
+                    last_v = mapped[-1][-1]
+                    alt = alternatives.get(last_v, "u" if last_v in "oɔ" else "i")
+                    mapped[-1] = mapped[-1][:-1] + alt
+                mapped.append(g)
+                run_converted = True
+            else:
+                if g != prev_g:
+                    prev_g, prev_ipa, run_converted = g, ipa, converted
+                    mapped.append(g)
+                else:
+                    mapped.append(g)
+                    prev_ipa = ipa
+                    run_converted = run_converted or converted
+        return mapped
+
+    def _map(self, ipa: str) -> tuple:
+        """Return (grapheme, converted). `converted` is True when the target writes
+        this phoneme differently from the source's own spelling (or the source has no
+        spelling for it), i.e. a merge/simplification actually happened."""
+        # 1) a real-language target's own writing: exact reading first (a target that
+        #    spells /tʰ/ as <th> still wins), aspiration-relaxed as its fallback (a
+        #    target with no /tʰ/ at all uses its /t/ reading). For the virtual
+        #    "universal" target this step is identical to the majority step below.
+        relaxed = _relax_aspiration(ipa) if self.relax_aspiration else ipa
+        if self.target != UNIVERSAL:
+            for form in (ipa, relaxed):
+                g = self._reverse.get(form)
+                if g is not None:
+                    break
+            else:
+                g = None
+        else:
+            g = None
+        if g is None:
+            # 2) the majority grapheme set. Rare aspirated phonemes win their vote by
+            #    tiny samples (e.g. /tɕʰ/ is written <q> by just 3 languages), so prefer
+            #    the relaxed, plain-phoneme majority (/tɕʰ/ reads like the /tɕ/ winner)
+            #    and keep the exact entry only as a last resort.
+            for form in (relaxed, ipa):
+                g = self._universal_reverse.get(form)
+                if g is not None:
+                    break
+            else:
+                g = None
+        # 3) a tone-marked or nasalised variant of a phoneme the table does know.
+        #    Source orthographies write tone on the vowel ("lɔ́lɔndai", "ɣɛ́i"), and the
+        #    accented form is absent from the survey, so it used to fall through to
+        #    step 4 — leaving a bare ɔ or ɛ in universal output once normalisation
+        #    stripped the accent, which is exactly the character universal exists to
+        #    remove. Retry on the base letter, keeping the mark off: the universal
+        #    orthography does not write tone.
+        if g is None and self.target == UNIVERSAL:
+            base = _strip_combining(ipa)
+            # A unit that is nothing but modifiers — a lone tone bar or ˤ emitted as
+            # its own unit — writes as nothing, the same as the other phonemes the
+            # universal orthography does not mark.
+            if ipa and not base:
+                return "", True
+            if base and base != ipa:
+                for form in (base, _strip_combining(relaxed)):
+                    g = self._universal_reverse.get(form)
+                    if g is not None:
+                        break
+                else:
+                    g = None
+
+        # 4) unmappable: pass the IPA unit through untouched.
+        if g is None:
+            return ipa, False
+        if not self._source_spelling:
+            return g, False
+        src = self._source_spelling.get(tie_affricates(ipa))
+        return g, src != g
+
+
+def convert_lang(text: str, source: str, target: str, *, sep: str = "") -> str:
+    """One-shot converter: ``convert_lang("Onyankopɔn", "twi", "ewe")``. Words are
+    kept whole by default; pass ``sep=" "`` for per-unit (phoneme-sequence) output."""
+    return GraphemeConverter(source, target).convert(text, sep=sep)
+
+
+def convert_to_ipa(text: str, source: str, *, sep: str = "") -> str:
+    """G2U2P pipeline: a language's graphemes -> universal graphemes -> IPA.
+
+    Writes the source in the universal majority-grapheme set first, then reads that
+    back to IPA, so every language phonemicizes along the same curated conventions
+    (Gemini-normalised spellings and aspiration relaxation included). Lossy by design:
+    two phonemes the universal set writes alike (e.g. /ɔ/ and /o/ both <o>) read back
+    as the single winner phoneme. ``sep=" "`` prints per-unit phonemes; the default
+    ``sep=""`` emits continuous IPA."""
+    universal = GraphemeConverter(source, UNIVERSAL).convert(text)
+    return _universal_g2p_engine().convert(universal, sep=sep)