Skip to main content

ALDashboard.translation

is_valid_mako_block​

def is_valid_mako_block(text: str) -> Tuple[bool, Optional[str]]

Return True if the provided text can be rendered as Mako without raising an error. Empty strings are treated as valid.

gpt_is_available​

def gpt_is_available() -> bool

Return True if the GPT API is available.

may_have_mako​

def may_have_mako(text: str) -> bool

Return True if the text appears to contain any Mako code, such as ${...} or % at the beginning of a line.

may_have_html​

def may_have_html(text: str) -> bool

Return True if the text appears to contain any HTML code, such as <p> or <div>.

translate_fragments_gpt​

def translate_fragments_gpt(
    fragments: Union[str, List[Tuple[int, str]]],
    source_language: str,
    tr_lang: str,
    interview_context: Optional[str] = None,
    special_words: Optional[Dict[int, str]] = None,
    model: Optional[str] = "gpt-5-nano",
    openai_base_url: Optional[str] = None,
    max_output_tokens: Optional[int] = None,
    max_input_tokens: Optional[int] = None,
    openai_api: Optional[str] = None,
    reasoning_effort: Optional[Literal["minimal", "low", "medium",
                                       "high"]] = "low"
) -> Dict[int, str]

Use an AI model to translate a list of fragments (strings) from one language to another and provide a dictionary with the original text and the translated text.

You can optionally provide an alternative model, but it must support JSON mode.

Arguments​

  • fragments - A list of strings to be translated.
  • source_language - The language of the original text.
  • tr_lang - The language to translate the text into.
  • special_words - A dictionary of special words that should be translated in a specific way.
  • model - The GPT model to use. The default is "gpt-5-nano"
  • openai_base_url - The base URL for the OpenAI API. If not provided, the default OpenAI URL will be used.
  • max_output_tokens - The maximum number of tokens to generate in the output.
  • max_input_tokens - The maximum number of tokens in the input. If not provided, it will be set to 4000.
  • openai_api - The OpenAI API key. If not provided, it will use the key from the configuration.
  • reasoning_effort - Controls the reasoning effort for thinking models like GPT-5. Defaults to "low".

Returns​

A dictionary where the keys are the indices of the fragments and the values are the translated text.

Translation Objects​

class Translation(NamedTuple)

file: DAFile​

an XLSX or XLIFF file

untranslated_segments: int​

Number of rows in the output that have untranslated text - one for each question, subquestion, field, etc.

translation_file​

def translation_file(yaml_filename: str,
                     tr_lang: str,
                     use_gpt=False,
                     use_google_translate=False,
                     openai_api: Optional[str] = None,
                     max_tokens=4000,
                     interview_context: Optional[str] = None,
                     special_words: Optional[Dict[int, str]] = None,
                     model: Optional[str] = None,
                     openai_base_url: Optional[str] = None,
                     max_input_tokens: Optional[int] = None,
                     max_output_tokens: Optional[int] = None,
                     reasoning_effort: Optional[Literal["minimal", "low",
                                                        "medium",
                                                        "high"]] = None,
                     validate_mako: Optional[bool] = True) -> Translation

Return a tuple of the translation file in XLSX format, plus a count of the number of words and segments that need to be translated.

The word and segment count only apply when filetype="XLSX".

This code was adjusted from the Flask endpoint-only version in server.py. XLIFF support was removed for now but can be added later.

Arguments​

  • yaml_filename - Fully qualified interview YAML path.
  • tr_lang - Target translation language (ISO code).
  • use_gpt - Whether to include GPT draft translations.
  • use_google_translate - Placeholder for legacy Google support.
  • openai_api - API key override.
  • max_tokens - Legacy max token setting (kept for backward compatibility).
  • interview_context - Optional context prompt to send with GPT calls.
  • special_words - Optional glossary to enforce terminology.
  • model - Preferred OpenAI model.
  • openai_base_url - Override the OpenAI base URL.
  • max_input_tokens - Optional override for input token limits.
  • max_output_tokens - Optional override for completion token limits.
  • reasoning_effort - Reasoning effort setting, used for GPT-5 models.
  • validate_mako - When True, retry GPT translations that break Mako syntax (default).