id_translation.Translator.translate

Translator.translate(translatable, names=None, *, ignore_names=None, copy=True, override_function=None, max_fails=1.0, reverse=False, fmt=None)

Translate IDs to human-readable strings.

Simplified process:

1. The map method performs name-to-source mapping (see DirectionalMapping).

2. The fetch method extracts IDs to translate and retrieves data (see TranslationMap).

3. Finally, the translate method applies the translations and returns to the caller.

See the Translation primer page for a detailed process description.

See also

🔑 This is a key event method. Exit-events are emitted on the ℹ️INFO-level if the Translator is online. Enter-events are always emitted on the 🪲DEBUG-level. See Key Event Records for details.

Parameters:

• translatable – A data structure to translate.

• names – Explicit names to translate. Derive from translatable if None. Alternatively, you may pass a dict on the form {name_in_translatable: source_to_use}.

• ignore_names – Names not to translate, or a predicate (NameType) -> bool.

• copy – If False, translate in-place and return None.

• override_function – A callable (name, sources, ids) -> Source | None. See Mapper.apply() for details.

• max_fails – The maximum fraction of IDs for which translation may fail. 1=disabled.

• reverse – If True, perform translations back to IDs. Offline mode only.

• fmt – A format string such as ‘{id}:{name}’ use. Default is Translator.fmt.

Returns:

A translated copy of translatable if copy=True, otherwise None.

Examples

Manual name-to-source mapping with a temporary name-only Format.

>>> n2s = {"lions": "animals", "big_cats": "animals"}
>>> translator.translate({"lions": 2, "big_cats": 2}, names=n2s, fmt="{name}")
{'lions': 'Simba', 'big_cats': 'Simba'}

Name mappings must be complete; any name not present in the keys will be ignored (left as-is).

Raises:

• UntranslatableTypeError – If type(translatable) cannot be translated.

• MissingNamesError – If names are not given and cannot be derived from translatable.

• MappingError – If any required (explicitly given) names fail to map to a source.

• MappingError – If name-to-source mapping is ambiguous.

• ValueError – If max_fails is not a valid fraction.

• TooManyFailedTranslationsError – If translation fails for more than max_fails of IDs.

• ConnectionStatusError – If reverse=True while the Translator is online.

• UserMappingError – If override_function returns a source which is not known, and mapper.on_unknown_user_override != 'ignore'.

See also

The ID_TRANSLATION_DISABLED variable.