Translation Helpers

pymdtools.translate translates plain text and Markdown with the MyMemory web API. Markdown translation keeps the document structure while translating text segments.

Common Usage

Translate plain text:

from pymdtools.translate import translate_txt

result = translate_txt("Hello", src="en", dest="fr")

Translate Markdown:

from pymdtools.translate import translate_md

translated = translate_md("# Hello", src="en", dest="fr")

Network access is required at runtime because translations are requested from the MyMemory API.

Translation text is sent to a third-party service. Do not submit secrets or regulated content without an appropriate data policy. Network failures keep the original text by default; on_error="raise" is available when a failed translation must stop the workflow.

Public API

Translate plain text and Markdown with the MyMemory web API.

The module exposes two public helpers:

MyMemory translates short segments through its REST /get endpoint. The API requires a q text parameter and a langpair parameter formatted as source|destination. A contact email can be sent with the de parameter to raise the daily free quota.

References

https://mymemory.translated.net/doc/spec.php https://mymemory.translated.net/doc/usagelimits.php

pymdtools.translate.translate_md(md_text: str, src: str = 'fr', dest: str = 'en', *, email: str | None = None, api_key: str | None = None, timeout: float = 10.0, on_error: Literal['keep_original', 'empty', 'raise'] = 'keep_original') → str

Translate Markdown text with MyMemory while preserving Markdown structure.

Mistune parses the Markdown and the renderer sends only plain text tokens to translate_txt(). Markdown syntax such as headings, emphasis, lists and links is therefore emitted by the renderer instead of being translated as raw markup.

Parameters:

  • md_text – Source Markdown text.

  • src – Source language code, for example "fr".

  • dest – Destination language code, for example "en".

  • email – Optional contact email sent to MyMemory as the de parameter.

  • api_key – Optional MyMemory private key.

  • timeout – Network timeout in seconds.

  • on_error – Forwarded to translate_txt().

Returns:

Translated Markdown text.

pymdtools.translate.translate_txt(text: str, src: str = 'fr', dest: str = 'en', *, email: str | None = None, api_key: str | None = None, timeout: float = 10.0, on_error: Literal['keep_original', 'empty', 'raise'] = 'keep_original') → str

Translate plain text with MyMemory.

Blank strings are returned unchanged. Long text is split into chunks of at most 500 UTF-8 bytes, which matches the MyMemory q parameter limit.

Parameters:

  • text – Source text.

  • src – Source language code, for example "fr".

  • dest – Destination language code, for example "en".

  • email – Optional contact email sent to MyMemory as the de parameter.

  • api_key – Optional MyMemory private key.

  • timeout – Network timeout in seconds.

  • on_error – Behavior when the API call fails: "keep_original" returns the source text, "empty" returns "" for backward compatibility, and "raise" propagates the exception.

Returns:

Translated text, unchanged blank text, or the configured fallback when the API call fails.