Skip to content

translate

utils.language.translate

Translate LaTeX text using CSV-based manual translations and Google Translate.

Classes:

  • LatexTranslator –

    Utility class for extracting and translating LaTeX text.

utils.language.translate.LatexTranslator 

LatexTranslator(
    original_text: str,
    destination_language: str,
    source_language: str = "en",
    custom_csv: Path | str | None = None,
)

Utility class for extracting and translating LaTeX text.

Supports translation between any language pair when using a CSV translation file. Falls back to Google Translate for text not found in the CSV.

If Google Translate fails (network error, API limit, etc.), the original text is preserved and the error is logged. Translation continues gracefully.

WARNING: uses Google Translate service when translations haven't been manually entered. When the service is unavailable, text will remain in the original language.

Examples:

Basic usage with default CSV:

>>> latex = r"\\text{Hello world} with formula $x = 5.2$"
>>> translator = LatexTranslator(latex, destination_language="nl")
>>> print(translator.text)
\\text{Hallo wereld} with formula $x = 5,2$

Using a custom CSV file:

>>> from pathlib import Path
>>> custom_csv = Path("my_translations.csv")
>>> # CSV contains: en,nl
>>> #                "Concrete strength","Betonsterkte"
>>> latex = r"\\section{Concrete strength}"
>>> translator = LatexTranslator(latex, "nl", custom_csv=custom_csv)
>>> str(translator)
'\\\\section{Betonsterkte}'

Translating from non-English source:

>>> latex_de = r"\\text{Hallo Welt}"
>>> translator = LatexTranslator(latex_de, destination_language="en", source_language="de")
>>> print(translator.text)
\\text{Hello World}

The translator handles various LaTeX commands: - Text commands: \text{}, \txt{}, \textbf{}, \textit{} - Sections: \section{}, \subsection{}, \subsubsection{}, \title{} - Captions: \caption{} - Lists: \item content - Tables: content within tabular environments - Equations: decimal separator conversion for certain languages (e.g.: '.' → ',' for Dutch)

Initialize the LatexTranslator class with text and destination language.

WARNING: uses Google Translate service when translations haven't been manually entered. When the services are not available, (sections of) text will be left in the original language.

Parameters:

  • original_text (str) –

    The LaTeX string to be translated.

  • destination_language (str) –

    The target language code (e.g., 'nl' for Dutch, full list on https://docs.cloud.google.com/translate/docs/languages).

  • source_language (str, default: 'en' ) –

    The source language code of the LaTeX document (default: 'en' for English).

  • custom_csv (Path | str, default: None ) –

    Optional custom path to the CSV file containing manual translations. Will use default 'translations.csv' declared in Blueprints.

    Warning: When no custom CSV is provided, the default 'translations.csv' file in Blueprints is used. This file may probably not contain translations for your specific use case and language pair. We will use Google Translate for missing translations, but results may vary.

    Therefore, it is recommended to provide a custom CSV file with manual translations for your specific use case and language pair: - column headers are language codes (e.g., 'en,nl,de,fr'). - each row contains translations for the same concept across different languages. - use '-' as a translation value to keep the source text unchanged for that language. - supports (multiple) wildcard patterns using '**' to match and preserve variable content.

    When a custom CSV is provided, it should follow the example format described below: 

    en, nl, de, fr
"Hello", "Hallo", "Hallo", "Bonjour"
"With formula **:", "Met formule **:", "Mit Formel **:", "-"
    With this CSV, you can translate en→nl, nl→fr, de→en, etc. Using the same file.

Source code in blueprints/utils/language/translate.py 
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
def __init__(
    self,
    original_text: str,
    destination_language: str,
    source_language: str = "en",
    custom_csv: Path | str | None = None,
) -> None:
    r"""
    Initialize the LatexTranslator class with text and destination language.

    WARNING: uses Google Translate service when translations haven't been manually entered.
    When the services are not available, (sections of) text will be left in the original language.

    Parameters
    ----------
    original_text : str
        The LaTeX string to be translated.
    destination_language : str
        The target language code (e.g., 'nl' for Dutch, full list on https://docs.cloud.google.com/translate/docs/languages).
    source_language : str, optional
        The source language code of the LaTeX document (default: 'en' for English).
    custom_csv : Path | str, optional
        Optional custom path to the CSV file containing manual translations. Will use default 'translations.csv' declared in Blueprints.

        Warning:
        When no custom CSV is provided, the default 'translations.csv' file in Blueprints is used.
        This file may probably not contain translations for your specific use case and language pair.
        We will use Google Translate for missing translations, but results may vary.

        Therefore, it is recommended to provide a custom CSV file with manual translations for your specific use case and language pair:
        - column headers are language codes (e.g., 'en,nl,de,fr').
        - each row contains translations for the same concept across different languages.
        - use '-' as a translation value to keep the source text unchanged for that language.
        - supports (multiple) wildcard patterns using '**' to match and preserve variable content.

        When a custom CSV is provided, it should follow the example format described below:
        ```
        en, nl, de, fr
        "Hello", "Hallo", "Hallo", "Bonjour"
        "With formula **:", "Met formule **:", "Mit Formel **:", "-"
        ```
        With this CSV, you can translate en→nl, nl→fr, de→en, etc. Using the same file.

    """
    self.original_text = original_text
    self.source_language = source_language
    self.destination_language = destination_language
    self.csv_path = str(custom_csv) if custom_csv else os.path.join(os.path.dirname(__file__), "translations.csv")
    self._translation = ""

utils.language.translate.LatexTranslator.text property 

text: str

Return the translated LaTeX string.

Returns:

  • str –

    The translated LaTeX string.