Ctrl+K

id_translation.Translator.translate#

Translator.translate(translatable, names=None, *, ignore_names=None, inplace=False, override_function=None, maximal_untranslated_fraction=1.0, reverse=False, fmt=None)[source]#

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.

  • inplace – If True, translate in-place and return None.

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

  • maximal_untranslated_fraction – 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 inplace=False, 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:
On this page