API Reference¶

def search(
    term: str,
    language_code: str,
    *,
    include_flatpak: bool = True,
    source_only: bool = False,
    translation_only: bool = False,
    whole_word: bool = False,
    on_progress: Callable[[str], None] | None = None,
) -> SearchResult:
    """Search for a term across all installed .mo translation files for a given language.

    Searches both source (usually English) text and translated strings by default.
    Results are organized by source category (system locale, Flatpak, GNOME
    extensions, KDE Plasmoids, etc.) and collected concurrently.

    Args:
        term: Text to search for. Search is case-insensitive.
        language_code: Language to search in. Accepts ISO 639-1 (e.g. ``fi``),
            ISO 639-2/3 (e.g. ``fin``), or GNU C locale codes (e.g. ``fi_FI``,
            ``pt_BR``). Run ``locale -a`` to list codes available on your system.
        include_flatpak: Search Flatpak application and runtime translations.
            Disable for faster searches if Flatpak results are not needed.
        source_only: Search only in source strings.
            Cannot be used with ``translation_only``.
        translation_only: Search only in translation strings.
            Cannot be used with ``source_only``.
        whole_word: Match whole words only instead of partial matching.
        on_progress: Optional callback invoked once per category before it is
            searched. Receives a human-readable status string, e.g.
            ``"Searching System Locale..."``. Useful for UI refresh, e.g. progress indicators.

    Returns:
        A [SearchResult][wittrans.models.SearchResult] containing all matches.

    Raises:
        InvalidLanguageCode: If the language code is not a valid two- or
            three-letter ISO 639 code or locale string.
        TranslationDirectoryNotFound: If no translation directories are found
            for the given language.
    """

    lang_code = language_code.lower()
    translation_paths = validate_language_paths(
        lang_code, include_flatpak=include_flatpak
    )

    category_results: list[CategoryResult] = []
    total_directories = 0
    total_mo_files = 0
    start_time = time.monotonic()

    with ThreadPoolExecutor() as executor:
        for cat in CATEGORIES:
            if on_progress is not None:
                on_progress(f"Searching {cat.display_name}...")

            category_paths = getattr(translation_paths, cat.key)

            results, mo_files = search_directory(
                category_paths,
                term,
                search_source=not translation_only,
                search_translation=not source_only,
                whole_word=whole_word,
                executor=executor,
            )

            total_directories += len(category_paths)
            total_mo_files += mo_files

            category_results.append(
                CategoryResult(
                    category=cat.key,
                    display_name=cat.display_name,
                    results=results,
                    directories_searched=len(category_paths),
                    mo_files_found=mo_files,
                )
            )

    duration = time.monotonic() - start_time
    total_matches = sum(
        len(file_result.matches)
        for cat in category_results
        for file_result in cat.results
    )

    return SearchResult(
        term=term,
        language_code=lang_code,
        categories=category_results,
        statistics=SearchStatistics(
            directories_searched=total_directories,
            mo_files_found=total_mo_files,
            total_matches=total_matches,
            search_duration_seconds=duration,
        ),
    )

def get_translations(
    language_code: str,
    *,
    include_flatpak: bool = True,
    on_progress: Callable[[str], None] | None = None,
) -> SearchResult:
    """Retrieve all translation strings from installed .mo files for a given language.

    Matches every entry in every translation file found for the language.
    Use this to retrieve all translations.
    The result can be very large depending on the number
    of installed .mo files and their content.

    Args:
        language_code: Language to retrieve translations for. Accepts ISO 639-1
            (e.g. ``fi``), ISO 639-2/3 (e.g. ``fin``), or GNU C locale codes
            (e.g. ``fi_FI``, ``pt_BR``).
        include_flatpak: Include Flatpak application and runtime translations.
            Disable for faster retrieval if Flatpak results are not needed.
        on_progress: Optional callback invoked once per category before it is
            searched. Receives a human-readable status string, e.g.
            ``"Searching System Locale..."``. Useful for progress indicators.

    Returns:
        A [SearchResult][wittrans.models.SearchResult] containing all translations.

    Raises:
        InvalidLanguageCode: If the language code is not a valid two- or
            three-letter ISO 639 code or locale string.
        TranslationDirectoryNotFound: If no translation directories are found
            for the given language.
    """
    return search(
        "",
        language_code,
        include_flatpak=include_flatpak,
        on_progress=on_progress,
    )