Arabic names and English product names in one call

TL;DR: Preserve captured spelling, catalog identity and spoken preference as separate values when Arabic names and English product labels share a call. Resolve only approved scoped aliases, keep collisions ambiguous, and treat normalization or pronunciation hints as text-processing tools rather than proof of identity.

---

A caller supplies a name, then mentions an English product. The application folds several spellings into one convenient lookup key and speaks a familiar pronunciation. The response sounds confident, but the selected person or item may be wrong.

The failure is a contract collapse. Recognition supplies a surface, a catalog supplies possible entities, and a speech policy supplies a rendering. Those values can be related without becoming interchangeable.

Start with three separate records: original captured surface, approved entity mapping and scoped speech preference. Retain an unknown or ambiguous result whenever the catalog evidence does not establish a unique candidate.

The multilingual task guide explains why text accuracy does not establish task success. This guide supplies an exact alias matcher with immutable values, a separately scoped pronunciation lookup and negative fixtures for the common shortcuts.

All examples are synthetic. The program does not recognize names from audio, identify a person, transliterate Arabic, validate phonemes or establish acoustic pronunciation quality for 60db Agent or another system.

Table of contents

1. Separate the captured surface from the entity
2. Define an approved alias scope
3. Keep normalization as a declared projection
4. Treat shared aliases as ambiguity
5. Run the bounded alias reference
6. Interpret the returned values
7. Keep pronunciation approval separate
8. Construct speech markup safely
9. Handle repairs without silent substitution
10. Review the catalog before release
11. Test the real speech boundary
12. Trace a mismatch to its owner
13. Compare phrase bias with catalog evidence
14. Freeze the supported catalog value shape
15. Test collisions created by text projections
16. Activate speech preferences through their own release
17. Audit one complete mismatch trace
18. Frequently asked questions
19. Begin with a shared alias

Separate the captured surface from the entity

The captured surface is the text your recognizer or capture interface supplied. Preserve it exactly under the evidence policy so a reviewer can see what the matcher actually received.

The entity ID belongs to the task's catalog or owning service. It should remain stable across approved display variants without implying that every visually similar spelling refers to that entity.

The spoken preference is a rendering instruction under a supported voice policy. A person can prefer a particular pronunciation while their canonical written name remains unchanged. A product can have a branded spoken form that differs from its literal label.

W3C's personal-name guidance describes why universal assumptions about name structure fail. Do not split or reorder a captured name merely because one application's fields expect a familiar first-name/last-name pattern.

The CLDR person-name specification addresses locale-sensitive name formatting. Formatting guidance does not determine pronunciation or resolve an ambiguous identity.

Keep the task boundary visible. A catalog match can propose an entity for confirmation, while authentication or authorization may require additional evidence. The matcher in this article does not establish that the speaker is the person whose name was matched.

The workflow enforcement guide explains the next step: candidate selection is evidence for a workflow, not a general permission to perform an external action.

Define an approved alias scope

An alias is an explicit mapping approved by the owning catalog process. Its record should name the entity, surface and context in which that relation is allowed.

The reference uses language and task context as scope fields. A real catalog can need additional dimensions such as tenant, product release or policy version, but those dimensions must come from the actual application contract rather than from guesses about the caller.

Do not promote a one-time transcription repair into a global alias automatically. A reviewer can approve a correction for one case without authorizing that spelling for every entity or language context.

For product names, decide whether a local display label, original English brand label and spoken preference refer to the same catalog object. Retain the owner-approved relation and avoid inventing translations during the live call.

For personal names, preserve the limits of the mapping. The same written surface or transliteration can be shared by different people. A unique match within a small supplied catalog is narrower than unique identity in the real world.

The Emirati task-fixture guide uses scoped aliases to test an intended entity across language switches. Its scope is a reviewed task fixture, not a claim that the language label itself verifies a name.

An alias release should be auditable. Keep the reason it was added, its reviewer approval and the collision checks performed against the current catalog. Do not discard earlier releases if they are needed to reproduce a previous task decision.

The cache-key guide explains why scope must survive reuse. A matching surface from another catalog or alias release cannot be restored as current evidence solely because its text is identical.

Keep normalization as a declared projection

Normalization can make defined text representations comparable under a chosen rule. It should not overwrite the captured literal or silently expand into accent removal, transliteration or visual matching.

Unicode normalization distinguishes canonical normalization from compatibility normalization. The reference exposes either exact comparison or an explicit NFC projection, keeping the original input unchanged in its result.

NFC equivalence does not establish that two people are the same person. It also does not make an unapproved surface an alias by itself. The projected comparison is applied only against the supplied approved catalog surfaces.

Compatibility transformations can erase distinctions relevant to an identifier. Do not use them as a default identity shortcut. If a task needs a different comparison policy, document that policy and test its collisions before approving it.

Unicode security mechanisms address confusable and mixed-script concerns. Similar appearance is a reason to inspect text under a declared policy, not a reason to merge identities automatically.

The RTL interface guide describes another distinction: visual order differs from logical source order. A label that looks right on screen can still carry a different logical identifier.

Keep normalization version evidence when it matters to reproduction. The artifact prints the runtime Unicode database version. Its small character fixtures do not claim conformance to every behavior of a newer Unicode specification or a provider's separate text-processing pipeline.

Treat shared aliases as ambiguity

A collision is a useful result. When the approved scope maps one candidate surface to several entity IDs, return the candidate set and ask the owning workflow for clarification.

Do not break the tie using catalog iteration order. Do not choose the most familiar spelling or a pronunciation preference as though it were independent identity evidence. Those shortcuts can make an unstable decision appear deterministic.

The reference sorts candidate IDs only to make its output reproducible. Sorting does not select a winner. The selected entity remains absent unless the candidate set contains exactly one approved entity.

The unfamiliar-surname guide explains the repair boundary. Keep the caller's original surface while asking for the missing distinction instead of silently substituting a familiar name.

An ambiguous result also differs from an unknown one. Unknown means no approved mapping exists under this scope and comparison policy. Ambiguous means multiple approved mappings exist. Both can require clarification while pointing to different catalog or task questions.

Do not use a generic yes to resolve an unspoken candidate set. The caller needs a meaningful distinction to confirm. The yes-but repair guide adds the related rule that a material correction invalidates earlier confirmation.

Run the bounded alias reference

Save the complete fence as scoped_aliases.py and run Python 3.12 or later. It prints a synthetic ambiguity result and a unique entity result whose canonical spelling and approved speech hint remain separate.

Trusted inputs are owner-approved catalog relations and pronunciation approvals. The code owns immutable supported value snapshots, scope comparisons and output classification. It does not verify the approval process, authenticate a person or execute a speech engine.

from dataclasses import dataclass, asdict, FrozenInstanceError
import json
import unicodedata


def required(value):
    return type(value) is str and bool(value.strip())


@dataclass(frozen=True)
class Alias:
    language: str
    context: str
    surface: str

    def __post_init__(self):
        if not all(required(x) for x in (self.language, self.context, self.surface)):
            raise ValueError("explicit alias scope and surface required")


@dataclass(frozen=True)
class Entity:
    identity: str
    canonical: str
    aliases: tuple

    def __post_init__(self):
        if not required(self.identity) or not required(self.canonical):
            raise ValueError("entity identity and canonical surface required")
        snapshot = tuple(self.aliases)
        if any(type(a) is not Alias for a in snapshot):
            raise ValueError("typed immutable aliases required")
        object.__setattr__(self, "aliases", snapshot)


@dataclass(frozen=True)
class Preference:
    entity: str
    language: str
    voice: str
    context: str
    hint: str
    approval: str

    def __post_init__(self):
        if not all(required(x) for x in
                   (self.entity, self.language, self.voice, self.context,
                    self.hint, self.approval)):
            raise ValueError("complete approved preference scope required")


def resolve(catalog, candidate, language, context, comparison="exact"):
    catalog = tuple(catalog)
    if (not all(required(x) for x in (candidate, language, context))
            or comparison not in ("exact", "nfc")
            or any(type(e) is not Entity for e in catalog)):
        raise ValueError("supported typed matching contract required")
    if len({e.identity for e in catalog}) != len(catalog):
        raise ValueError("duplicate entity identity")
    def project(value):
        return value if comparison == "exact" else unicodedata.normalize("NFC", value)
    ids = tuple(sorted({e.identity for e in catalog for a in e.aliases
                        if (a.language, a.context) == (language, context)
                        and project(a.surface) == project(candidate)}))
    disposition = "unknown" if not ids else "unique" if len(ids) == 1 else "ambiguous"
    selected = ids[0] if len(ids) == 1 else None
    canonical = next((e.canonical for e in catalog if e.identity == selected), None)
    return {"original_surface": candidate, "comparison": comparison,
            "disposition": disposition, "candidate_ids": ids,
            "selected_entity": selected, "canonical_surface": canonical}


def speech_hint(preferences, entity, language, voice, context):
    preferences = tuple(preferences)
    if not all(required(x) for x in (entity, language, voice, context)):
        raise ValueError("explicit speech scope required")
    if any(type(p) is not Preference for p in preferences):
        raise ValueError("typed preferences required")
    matches = tuple(p for p in preferences
                    if (p.entity, p.language, p.voice, p.context) ==
                       (entity, language, voice, context))
    return matches[0] if len(matches) == 1 else None


def tests():
    source = [Alias("mixed", "catalog", "demo shared")]
    first = Entity("entity-a", "Original A", source)
    second = Entity("entity-b", "Original B", (Alias("mixed", "catalog", "demo shared"),))
    source.clear()
    collision = resolve((first, second), "demo shared", "mixed", "catalog")
    assert collision["disposition"] == "ambiguous"
    assert collision["selected_entity"] is None
    assert collision["candidate_ids"] == ("entity-a", "entity-b")
    unique = resolve((first,), "demo shared", "mixed", "catalog")
    assert unique["canonical_surface"] == "Original A"
    assert resolve((first,), "demo shared extra", "mixed", "catalog")["disposition"] == "unknown"
    assert resolve((first,), "demo shared", "other", "catalog")["disposition"] == "unknown"
    assert resolve((first,), "demo shared", "mixed", "person")["disposition"] == "unknown"
    marked = Entity("marked", "Original marked", (Alias("mixed", "catalog", "caf\u00e9"),))
    decomposed = "cafe\u0301"
    assert resolve((marked,), decomposed, "mixed", "catalog")["disposition"] == "unknown"
    normalized = resolve((marked,), decomposed, "mixed", "catalog", "nfc")
    assert normalized["selected_entity"] == "marked"
    assert normalized["original_surface"] == decomposed
    assert resolve((marked,), "cafe", "mixed", "catalog", "nfc")["disposition"] == "unknown"
    other_marked = Entity("other-marked", "Other canonical", (Alias("mixed", "catalog", decomposed),))
    assert resolve((marked, other_marked), decomposed, "mixed", "catalog", "nfc")["disposition"] == "ambiguous"
    changed_report = dict(unique)
    changed_report["canonical_surface"] = "caller annotation"
    assert resolve((first,), "demo shared", "mixed", "catalog")["canonical_surface"] == "Original A"
    preference = Preference("entity-a", "mixed", "demo-voice", "catalog",
                            "synthetic speech hint", "approval-demo")
    assert speech_hint((preference,), "entity-a", "mixed", "demo-voice", "catalog") == preference
    assert speech_hint((preference,), "entity-b", "mixed", "demo-voice", "catalog") is None
    assert speech_hint((preference,), "entity-a", "mixed", "other-voice", "catalog") is None
    assert speech_hint((preference, preference), "entity-a", "mixed", "demo-voice", "catalog") is None
    try:
        first.canonical = "rewritten"
    except FrozenInstanceError:
        pass
    else:
        raise AssertionError("canonical value was writable")
    for bad in (lambda: resolve((first, first), "demo shared", "mixed", "catalog"),
                lambda: resolve((first,), "", "mixed", "catalog"),
                lambda: Preference("entity-a", "mixed", "voice", "catalog", "hint", "")):
        try:
            bad()
        except ValueError:
            pass
        else:
            raise AssertionError("invalid catalog evidence accepted")
    print(json.dumps({"evidence": "synthetic_text", "unicode_database": unicodedata.unidata_version,
                      "ambiguous": collision, "unique": unique,
                      "approved_hint": asdict(preference)}, ensure_ascii=False, sort_keys=True))
    print("synthetic alias, collision, snapshot and preference fixtures passed")


if __name__ == "__main__":
    tests()

The function returns a fresh report dictionary, not an approved mutable proposal retained by the catalog. Caller changes to that report cannot mutate the frozen entity or preference records. A downstream authorization controller must still own and freeze its own supported proposal values.

Interpret the returned values

The ambiguity result retains the original candidate surface and all matching entity IDs. It intentionally returns no selected entity or canonical surface for that case.

The unique result names the one approved catalog candidate under the supplied scope. Its canonical surface comes from the catalog, while the original captured surface remains available independently. Neither field is overwritten by a pronunciation hint.

The printed speech preference is a synthetic approved record, not an audible sample. It demonstrates separate entity, language, voice, context and approval provenance. A real adapter needs the actual provider-supported representation and a listening review.

A dictionary result can be serialized or inspected without becoming an authorization token. The task-outcome guide describes why intended entity, confirmation and completed business action need separate observations.

Review the exact and NFC cases together. Exact comparison leaves the decomposed candidate unknown when only the composed approved surface exists. The explicit NFC mode can match that approved relation while preserving the original literal. Removing the accent still remains unknown.

Those tests establish a narrow textual rule. They do not prove Arabic transliteration quality, pronunciation similarity or person identity. The example uses a small Latin combining-mark fixture to make the normalization boundary inspectable without presenting generated Arabic as reviewed linguistic evidence.

Keep pronunciation approval separate

An approved speech hint needs an owner and scope. The reference requires an entity, language, voice, task context and approval reference before returning a preference.

A preference for one person must not transfer to another person who shares a spelling. A hint tested with one voice should not silently become approved for a different voice or language configuration. Keep those changes visible as new review work.

A historical developer question about phonetic name pronunciation asks how to render supplied pronunciation information. It is a useful engineering question, while current provider support and listening evidence own the actual answer.

The pronunciation-dictionary release guide explains how to version the approved content and activation boundary. A text fixture can verify scope and immutable release metadata without establishing how the active voice will sound.

Keep missing preference and conflicting preference distinct in the real adapter's evidence. The small helper returns no preference unless exactly one record matches. A richer application can expose the candidate approvals for review instead of treating absent output as permission to invent a pronunciation.

The technical-abbreviation guide provides another scope example. The same written token can need different spoken treatment in different contexts, so a global substitution is weaker than an explicit task-specific speech policy.

Construct speech markup safely

The SSML specification defines elements for pronunciation, aliases and interpretation. The Pronunciation Lexicon Specification describes graphemes, aliases and phonemes under its own contract.

Those standards describe representations, not universal engine support. Check which elements, alphabets and language combinations the actual speech adapter supports before using them in a trial.

Untrusted captured text should become serialized text content inside an approved markup structure. Do not concatenate it into element names, attributes or an unrestricted markup fragment. A product label that resembles XML must remain the label rather than become a speech command.

Keep pronunciation hints from a trusted approved source. A caller-provided string is evidence to review, not an automatically approved phoneme or external lexicon URL. The offline matcher does not fetch remote resources or construct SSML.

The mixed-script speech-preparation guide examines that next adapter boundary. Preserve logical source text and make supported rendering transformations explicit so the speech request can be inspected separately from the canonical record.

A listening test should use the exact generated request and active voice configuration. Inspecting the XML or lexicon text can detect a serialization defect, while actual sound still requires a supported speech and playback observation.

Handle repairs without silent substitution

A caller can correct the spelling, the intended entity or the preferred spoken form. Ask which field changed instead of treating every repair as a global replacement of the entire record.

A spelling repair can create a new captured surface while leaving identity unresolved. An entity repair can invalidate a previous candidate and confirmation. A pronunciation preference can change speech rendering while preserving the canonical spelling.

The spoken correction guide explains the revision boundary. Keep the current value separate from older partial observations, and do not allow a delayed earlier result to restore an obsolete candidate.

The partial-transcript guide provides the related adapter rule. A partial name hypothesis should not be committed as a confirmed catalog selection before the capture contract has enough evidence.

Use a clarification that exposes the missing distinction. When two entities share an alias, provide a task-appropriate differentiator under the application's privacy policy. Do not require a caller to approve an ambiguous name without knowing which entity the system means.

A material correction must invalidate prior confirmation. If an asynchronous speech or lookup request finishes later, recheck the current candidate and policy revision before using its result. The alias matcher itself is synchronous and does not claim to enforce those live workflow checks.

Review the catalog before release

Treat alias additions as behavior changes. A new surface can create a collision with an existing entity, change an unknown result into a candidate or expand the set of tasks in which a name is recognized.

Review both the new alias and the whole affected scope. An isolated positive test can show that the desired entity becomes reachable while missing the new ambiguity it creates elsewhere in the catalog.

The regression-testing guide explains how to retain that boundary. Keep positive exact matches, unknown nearby surfaces, shared aliases, scope mismatches and normalization collisions as independent fixtures.

Preserve canonical values and approved speech preferences independently through the change. Updating an alias should not silently rewrite the original spelling, activate another voice's hint or grant permission for an external action.

The concurrent-settings guide is relevant during activation. A preference or catalog release used by one call must not leak into another task's state through a shared mutable configuration object.

Version the release and preserve the earlier snapshot when it is needed to explain past decisions. A later corrected alias set should not be used to reconstruct a historical match as though the earlier system had access to it.

Test the real speech boundary

A text fixture establishes what the application submitted or selected. It does not establish the sound produced by the engine, the signal emitted by a device or what a caller understood.

Keep the speech request, provider configuration, output representation and selected playback observation joined through stable synthetic or permitted trial identities. A listening judgment without the corresponding request cannot distinguish a dictionary defect from another rendering configuration.

The playback evidence guide explains why local write acceptance and acoustic delivery differ. Use the strongest claim supported by the actual observation rather than labeling every callback heard.

For multilingual names, use reviewers qualified for the actual declared language/task context. This guide provides no verified Emirati or Egyptian pronunciation and does not treat an English phonetic spelling as a universal Arabic pronunciation reference.

The short-and-long response consistency guide provides a useful trial boundary. Hold the approved content and voice policy fixed while examining whether different request segmentation changes the perceived result.

Do not accept a pronunciation merely because it sounds plausible to an unqualified reviewer. Retain uncertainty and allow the caller-preference workflow to collect better evidence where appropriate. A confident rendering can still represent the wrong entity or the wrong preference scope.

Trace a mismatch to its owner

When a call uses the wrong name or product, preserve the sequence of observations. Inspect captured surface, alias release, matching scope, candidate set, confirmation revision, speech preference and actual request before assigning a cause.

A recognizer can supply the right surface while an overly broad matcher selects the wrong entity. A matcher can select the correct entity while a preference from another voice changes the spoken result. A correct request can still produce an unmeasured or disputed listening outcome.

The following table compares those evidence boundaries. A check means the supplied evidence can establish the named property under its declared contract; a cross means it cannot establish it alone.

The observability guide describes how to join those boundaries without copying private call content into every log. Keep the minimum evidence required to reproduce the mismatch and retain access controls for any real source material.

This article reports no pronunciation accuracy or identity-verification result. Its executable contract is the deterministic alias and preference boundary, with real audio and authorization left to their appropriate adapters.

Compare phrase bias with catalog evidence

A phrase list and an approved alias solve different problems. A phrase list influences a supported recognition operation, while an alias describes a catalog relation that the task owner has approved.

The Azure phrase-list documentation describes a recognition-biasing feature. It does not establish that the speaker said the supplied phrase or that the recognized surface identifies a unique object.

Keep the hint configuration in the recognition policy snapshot. Keep the alias release in the catalog policy snapshot. If either changes, record which boundary the intervention is intended to repair before comparing results.

A trial that inserts the expected answer into a hint list for only one run is answering a particular assisted-recognition question. It cannot be presented as an unqualified comparison of general name recognition. Preserve that condition and its permitted task scope.

A correctly recognized hinted surface can still be ambiguous in the catalog. The matcher should return all approved entities in scope rather than using the hint itself as another vote for the desired one.

A wrong surface can also match an approved alias for a different object. That result is locally consistent with the catalog while wrong for the caller's intended task. The evaluation needs the independent entity reference to identify the failure.

Use separate fixtures for these paths. Feed the exact approved surface to test the matcher. Feed an unapproved neighboring surface to test unknown handling. Then use actual reviewed audio to test whether the recognition adapter supplies the intended surface under its declared hint configuration.

The language-policy evaluation guide provides the comparison discipline. Keep source cases fixed, retain stable settings separately from per-item audit evidence and avoid attributing every task improvement to the recognizer.

Freeze the supported catalog value shape

An immutable record must own the values that its approval describes. Merely placing a caller-owned list inside a frozen container can leave the approved alias set writable through another reference.

The Entity constructor copies the supplied aliases into a tuple and requires each element to be a frozen Alias. The positive fixture clears the original source list after construction, then confirms that the entity still has the approved matching surface.

This is a deliberately bounded shape. Alias fields are strings, whose values are immutable under normal Python use. The constructor does not claim to freeze arbitrary custom objects, dictionaries or nested mutable values.

The canonical field is also frozen. The regression attempts ordinary property rebinding and expects an error. That establishes the supported application boundary without claiming that Python object internals are a security sandbox against hostile reflective code.

The returned match report is a fresh dictionary. A caller can annotate or change that report without changing the catalog's canonical value. If the report is later used as an approved external-action proposal, the owning controller must copy and freeze its own supported shape at that separate boundary.

Do not pass a dictionary through several tasks and call it approved because one stage inspected it earlier. A later alias or canonical change can invalidate the meaning of the selected entity. Keep the approved release identity beside any operation that relies on it.

The spoken-answer cache guide explains a related reuse problem. A historical answer can remain available while the facts or policy that made it correct have changed. A catalog result needs the same discipline when its alias release changes.

When replacing a catalog snapshot, validate the new snapshot before activation. Do not mutate the active tuple in place or let a partially constructed release become visible to concurrent calls. The tutorial does not implement a live activation service; it defines the immutable value that such an adapter would own.

Test collisions created by text projections

A comparison projection can change the collision set. Two approved literals that are distinct under exact comparison can become equivalent under a declared normalization rule, so testing only a single successful normalized match is insufficient.

Construct a synthetic pair whose aliases have canonically equivalent representations under NFC. Under the NFC comparison mode, both entity IDs should appear in the candidate set. The matcher must return ambiguous instead of selecting whichever entity was inserted first.

Keep the original candidate surface in that result. A reviewer should be able to distinguish the literal input from the projection used for comparison. Replacing the source with its normalized form would make that distinction harder to inspect later.

Test a change outside canonical equivalence too. Removing a mark, changing case or replacing a letter with a visually similar character should remain unknown unless an approved alias and comparison policy explicitly support it.

The standard defines textual properties; the task owner defines which approved relations may use them. That separation permits useful normalization without implying that normalization discovers real-world identity or authorizes a business action.

For Arabic material, do not invent a broad folding rule from a few examples. Review the actual catalog and task requirements with qualified owners. This article intentionally avoids presenting a generated set of Arabic variants as a validated linguistic policy.

A collision audit should retain both entity identities and their scopes. The right repair may be a narrower context, an explicit clarification question or a rejected alias addition. Deleting one candidate merely to restore a unique result can hide a legitimate ambiguity.

Retain those collisions in regression fixtures after the catalog is corrected. A future normalization or import change can reintroduce them even when the original application code is unchanged.

Activate speech preferences through their own release

A preference record documents intended speech treatment, but its existence does not prove that the active speech adapter accepted or used it. Separate approved content, release selection and actual request evidence.

The offline helper requires one exact scope match. Two matching preference records return no hint rather than selecting by iteration order. A real review interface should expose the conflict so an owner can decide which release or approval is current.

Do not infer the active voice from a display name alone. Keep the provider-supported configuration identity and relevant language/context fields in the adapter contract. A voice change can require another listening check even when the intended phonetic representation remains the same.

Preserve approval provenance with the preference. A short synthetic approval string in the fixture demonstrates the field shape only. It is not evidence that a qualified reviewer approved the pronunciation or that the application has permission to use a person's name.

A live activation step needs its own authorization and rollback boundary. This article neither activates a dictionary nor downloads an external lexicon. Its result can be reviewed before an adapter is permitted to affect speech output.

Inspect the exact text or markup submitted after selection. Escaping, substitution and segmentation can alter the request between preference lookup and synthesis. A passing alias test does not certify that downstream transformation.

The audio-chunk guide describes another boundary that can affect a listening trial. Preserve the actual output representation and segmentation when comparing two speech-policy releases so a timing change is not mistaken for a pronunciation change.

Keep the old release available for reproduction under the appropriate access controls. If a caller reports an incorrect spoken form, reconstruct the release and scope actually used instead of testing only the newest corrected preference.

Audit one complete mismatch trace

Choose one synthetic mismatch and follow it through every owned boundary. Start with the supplied surface, then the exact scope and catalog release, then the candidate set, current confirmation and any independently approved speech preference.

Ask which observation would falsify each current explanation. If the wrong surface entered the matcher, inspect capture evidence. If the expected surface returned multiple IDs, inspect alias scope and collisions. If the selected entity was correct but spoken output differed, inspect preference selection and the actual request.

Keep authorization outside that trace unless the task collected its own evidence. A unique name match cannot authenticate a person, and a plausible spoken confirmation cannot establish that an external action was permitted or completed.

The identifier-capture guide provides a useful complementary workflow: gather the missing distinction under a declared capture contract rather than guessing from a name's appearance.

End the trace with an explicit known or unknown disposition at each boundary. That record directs the next experiment without collapsing every name-related failure into ASR or every sound-related failure into the pronunciation dictionary.

Keep whitespace handling explicit at the capture boundary. The helper rejects an empty or whitespace-only candidate, but it does not trim a nonempty surface before matching. That distinction prevents input validation from silently becoming another alias-normalization rule. If a live adapter trims transport padding, record that transformation and preserve the raw value under the evidence policy.

The same caution applies to case and punctuation. A product label embedded inside a longer identifier is not an exact alias match. A punctuation mark may belong to the identifier rather than to surrounding prose. Decide the field boundary before comparing the supplied string, and keep a negative substring fixture so later convenience changes cannot broaden the matcher unnoticed.

When exporting the result, retain separate fields instead of constructing one display label that mixes canonical spelling and speech preference. A reviewer should be able to compare the original candidate, selected catalog entity and approved rendering without parsing a human-facing sentence. The printed synthetic record demonstrates that separation; a production log still needs its own access-control and retention policy.

A display formatter can present those values attractively without changing their identity contract. Treat formatting as another projection, preserve the source values and check that a copied or serialized identifier remains the intended literal before using it at an external boundary.

---

Frequently asked questions

How do names differ from product labels in capture?

Both need the original captured surface, but their catalogs and approval rules can differ. A product alias does not establish a person's identity, and a personal pronunciation preference should not become a global product substitution.

Why separate recognition from entity matching?

Recognition supplies a text hypothesis while matching compares that surface with a scoped catalog. Keeping them separate lets you identify whether a wrong task result began with audio recognition or with a later interpretation rule.

Can a transliteration identify a person uniquely?

Not by itself. Different people can share a written surface or transliteration, so preserve ambiguity and use the task's additional identification or confirmation contract.

When should an accepted spelling become an alias?

Only after approval under the catalog's scope and collision policy. A correction accepted in one call is not automatic permission to add that surface globally.

Who approves Arabic name variants?

Use the owning catalog process and reviewers qualified for the declared context. Preserve approval provenance and uncertainty rather than treating generated strings as verified linguistic references.

Should Arabic diacritics be removed?

Do not remove them by default for identity matching. If a task approves a comparison projection, preserve the original surface and test collisions under that exact policy.

What does Unicode NFC guarantee?

It supplies a defined canonical normalization form. It does not prove person identity, authorize letter folding or guarantee that a speech engine will pronounce the normalized string correctly.

Can confusable text be the same entity?

Only an approved entity relation can establish that catalog mapping. Visual similarity alone should not merge records; preserve the literal and apply the declared inspection or clarification policy.

How do I handle duplicate aliases?

Collect the matching entity IDs under the same scope and return ambiguous when there is more than one. Sorting the IDs makes output stable without selecting an arbitrary winner.

Should matching be case-insensitive?

Only when the task explicitly approves that comparison rule. The reference uses exact matching or a declared NFC projection; it does not silently fold case or change identifiers.

Can phrase hints prove a correct match?

No. Hints can bias a supported recognizer toward supplied terms, while intended entity, current confirmation and external completion still require separate evidence.

How should a caller repair an entity?

Create a new current candidate under the workflow's revision contract and invalidate prior confirmation. Keep older recognition or lookup results from restoring the replaced value.

Where should pronunciation hints be stored?

Keep them in a separately approved record scoped to the entity, language, voice and task context. Preserve canonical spelling and the original captured surface independently.

Does a phoneme string change canonical spelling?

It should not. A pronunciation representation is speech-rendering evidence under a supported adapter; it does not replace the catalog's canonical text or establish identity.

How do I test names without customer data?

Use clearly synthetic entities and approved artificial alias relations to test the application contract. Real linguistic or acoustic claims still require an appropriate reviewed corpus and consented trial.

What should unknown entities return?

Return an explicit unknown disposition and preserve the original surface. Do not substring-match, choose a nearest spelling or invent an entity so the workflow can continue without clarification.

Can product names remain in English?

Yes, when that is the task's approved catalog and speech policy. Do not translate or respell them automatically merely because the surrounding utterance uses Arabic.

How should bilingual reviewers label uncertainty?

Retain the uncertain field and review provenance separately from confirmed evidence. A reviewer may understand the product while remaining uncertain about a neighboring name or pronunciation.

What does an entity fixture fail to measure?

It does not measure recognition, actual speech output, acoustic delivery, comprehension or authorization. The reference establishes only its supplied alias, normalization and speech-preference scope rules.

How do I version alias changes?

Preserve an immutable release and its approval/collision evidence. Keep earlier releases available when needed for reproduction, and repeat the relevant text and listening checks before activation.

Begin with a shared alias

Run the complete fence and inspect the ambiguity result before looking at the unique match. Confirm that neither catalog order nor a pronunciation preference chooses an entity from a collision.

Then add one approved scoped alias and retain the unknown and conflicting controls. Keep canonical spelling, captured surface and speech preference separate as the real adapter is introduced.

Use a qualified listening trial only when you need a claim about actual speech. The first useful engineering result is a reproducible boundary that prevents a plausible rendering from silently becoming identity evidence.