Python API¶

The stable public Python API is intentionally small. The package exports run_translation and run_review from co_op_translator.api; most lower-level modules under core, config, review, and utils are implementation details used by the CLI and API entry points.

from co_op_translator.api import run_review, run_translation

Public entry points¶

co_op_translator.api.run_translation ¶

run_translation(language_codes: str, root_dir: str = '.', update: bool = False, images: bool = False, markdown: bool = False, notebook: bool = False, debug: bool = False, save_logs: bool = False, yes: bool = True, add_disclaimer: bool = False, translations_dir: str | None = None, image_dir: str | None = None, root_dirs: Iterable[str] | None = None, groups: Iterable[tuple[str, str | None]] | None = None, repo_url: str | None = None, glossaries: Iterable[str] | None = None, dry_run: bool = False) -> None

Programmatic translation entrypoint mirroring the translate CLI options.

co_op_translator.api.run_review ¶

run_review(language_codes: str | Iterable[str] = 'all', root_dir: str = '.', update: bool = False, images: bool = False, markdown: bool = False, notebook: bool = False, debug: bool = False, save_logs: bool = False, yes: bool = True, add_disclaimer: bool = False, translations_dir: str | None = None, image_dir: str | None = None, root_dirs: Iterable[str] | None = None, groups: Iterable[tuple[str, str | None]] | None = None, repo_url: str | None = None, glossaries: Iterable[str] | None = None, dry_run: bool = False, changed_from: str | None = None, output_format: str = 'text', fail_on_warnings: bool = False) -> ReviewSummary

Programmatic deterministic review entrypoint.

The signature intentionally mirrors run_translation where possible so automation can switch between translate and review workflows with minimal branching. Review ignores mutating translation-only options such as update, yes, add_disclaimer, repo_url, glossaries, and dry_run.

Typical usage¶

Translate Markdown files in the current project into Korean and Japanese:

from co_op_translator.api import run_translation

run_translation(
    language_codes="ko ja",
    markdown=True,
)

Translate only notebooks from a specific project root:

from co_op_translator.api import run_translation

run_translation(
    language_codes="fr",
    root_dir="./my-course",
    notebook=True,
)

Preview translation volume without writing files:

from co_op_translator.api import run_translation

run_translation(
    language_codes="es de",
    root_dir="./my-course",
    markdown=True,
    dry_run=True,
)

Translate multiple content roots in one call:

from co_op_translator.api import run_translation

run_translation(
    language_codes="ko",
    markdown=True,
    root_dirs=["./docs", "./labs"],
)

Write translations into explicit output groups:

from co_op_translator.api import run_translation

run_translation(
    language_codes="ja",
    markdown=True,
    groups=[
        ("./course-a", "./localized/course-a"),
        ("./course-b", "./localized/course-b"),
    ],
)

Use a per-language placeholder when each language should contain a nested subdirectory:

from co_op_translator.api import run_translation

run_translation(
    language_codes="ko",
    markdown=True,
    groups=[
        ("./course", "./translations/<lang>/course"),
    ],
)

Run deterministic review checks without API credentials:

from co_op_translator.api import run_review

run_review(
    language_codes="ko ja",
    root_dir="./my-course",
    markdown=True,
    notebook=True,
)

Review only files changed against a base ref and print GitHub-flavored output:

from co_op_translator.api import run_review

run_review(
    language_codes="ko",
    root_dir="./my-course",
    markdown=True,
    notebook=True,
    changed_from="origin/main",
    output_format="github",
)

Translation parameters¶

Parameter	Type	Default	Purpose
`language_codes`	`str`	Required	Space-separated target language codes, such as `"ko ja fr"`, or `"all"`. Alias codes are normalized to canonical BCP 47 values.
`root_dir`	`str`	`"."`	Project root for a single translation target. Ignored when `root_dirs` or `groups` are supplied.
`update`	`bool`	`False`	Delete and recreate existing translations for the selected languages.
`images`	`bool`	`False`	Include image translation. Requires Azure AI Vision configuration.
`markdown`	`bool`	`False`	Include Markdown translation.
`notebook`	`bool`	`False`	Include Jupyter notebook translation.
`debug`	`bool`	`False`	Enable debug logging.
`save_logs`	`bool`	`False`	Save DEBUG-level log files under the root `logs/` directory.
`yes`	`bool`	`True`	Auto-confirm prompts for programmatic and CI usage.
`add_disclaimer`	`bool`	`False`	Add machine translation disclaimers to translated Markdown and notebooks.
`translations_dir`	`str \\| None`	`None`	Custom text translation output directory. Relative paths resolve against each root.
`image_dir`	`str \\| None`	`None`	Custom translated image output directory. Relative paths resolve against each root.
`root_dirs`	`Iterable[str] \\| None`	`None`	Multiple roots that share the same output settings.
`groups`	`Iterable[tuple[str, str \\| None]] \\| None`	`None`	Explicit `(root_dir, translations_dir)` pairs. Takes precedence over `root_dirs`.
`repo_url`	`str \\| None`	`None`	Repository URL used when rendering README language table guidance.
`glossaries`	`Iterable[str] \\| None`	`None`	Glossary terms to preserve during translation. Duplicates and blank terms are normalized.
`dry_run`	`bool`	`False`	Estimate translation volume and preview migration behavior without writing files.

If none of markdown, notebook, or images are set, the API translates all supported types: Markdown, notebooks, and images.

Review parameters¶

run_review intentionally mirrors the run_translation signature where possible so automation can switch between translation and review workflows with minimal branching.

Parameter	Type	Default	Purpose
`language_codes`	`str \\| Iterable[str]`	`"all"`	Target language folders to review. Space-separated strings and iterables are accepted. `"all"` reviews every discovered translation language.
`root_dir`	`str`	`"."`	Project root for a single review target. Ignored when `root_dirs` or `groups` are supplied.
`markdown`	`bool`	`False`	Include Markdown and MDX source files.
`notebook`	`bool`	`False`	Include Jupyter notebook source files.
`images`	`bool`	`False`	Reserved for parity with translation options. Link references to images are checked from Markdown.
`translations_dir`	`str \\| None`	`None`	Custom text translation output directory. Relative paths resolve against each root.
`root_dirs`	`Iterable[str] \\| None`	`None`	Multiple roots that share the same output settings.
`groups`	`Iterable[tuple[str, str \\| None]] \\| None`	`None`	Explicit `(root_dir, translations_dir)` pairs. Takes precedence over `root_dirs`.
`changed_from`	`str \\| None`	`None`	Git ref used to limit review to changed source files.
`output_format`	`str`	`"text"`	Review output format. Supported values are `"text"` and `"github"`.
`fail_on_warnings`	`bool`	`False`	Treat warnings as failures in addition to errors.
`debug`	`bool`	`False`	Enable debug logging.
`save_logs`	`bool`	`False`	Save DEBUG-level log files under the root `logs/` directory.

If none of markdown, notebook, or images are set, the API reviews Markdown, notebooks, and image link references where applicable. Review does not call an LLM provider and does not require API keys.

Configuration requirements¶

run_translation checks configuration before translating:

An LLM provider is required. Configure either Azure OpenAI or OpenAI.
Image translation requires Azure AI Vision in addition to the LLM provider.
The API runs lightweight connectivity checks before translation begins.

Required Azure OpenAI variables:

AZURE_OPENAI_API_KEY="..."
AZURE_OPENAI_ENDPOINT="https://<resource>.openai.azure.com/"
AZURE_OPENAI_MODEL_NAME="gpt-4o"
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="<deployment>"
AZURE_OPENAI_API_VERSION="2024-12-01-preview"

Required OpenAI variables:

OPENAI_API_KEY="..."
OPENAI_CHAT_MODEL_ID="gpt-4o"

Required Azure AI Vision variables for image translation:

AZURE_AI_SERVICE_API_KEY="..."
AZURE_AI_SERVICE_ENDPOINT="https://<resource>.cognitiveservices.azure.com/"

run_review is deterministic and does not require Azure OpenAI, OpenAI, or Azure AI Vision configuration.

Behavior notes¶

The API prints progress and estimate summaries through Click, matching the CLI user experience.
dry_run=True computes estimates using virtual README updates, but does not write the README or translation files.
groups are processed sequentially. A single aggregate estimate is printed before work begins.
When image translation is selected, missing Vision configuration raises an error before translation starts.
Existing alias-based language folders are detected and can be migrated to canonical language folder names as part of the run.
run_review fails on missing translated files, missing or stale translation metadata, malformed Markdown frontmatter/code fences, and invalid translated notebook JSON.
run_review reports missing local Markdown and image link targets as warnings by default.

Internal call path¶

The API delegates to the same core implementation used by the CLI:

Translation:

co_op_translator.api.translation.run_translation
co_op_translator.config.Config, LLMConfig, and VisionConfig
co_op_translator.core.project.ProjectTranslator
co_op_translator.core.project.TranslationManager
Markdown, notebook, text, and image translators under co_op_translator.core

Review:

co_op_translator.api.review.run_review
co_op_translator.review.targets.build_review_targets
co_op_translator.review.runner.ReviewRunner
Deterministic checks under co_op_translator.review.checks

The following classes are useful for maintainers, but are not exported as the package-level stable API.

Class	Module	Responsibility
`ProjectTranslator`	`co_op_translator.core.project.project_translator`	Coordinates project-level translation, directory management, per-language metadata normalization, and delegation to Markdown, notebook, and image translators.
`TranslationManager`	`co_op_translator.core.project.translation`	Performs the async file processing work for Markdown, notebooks, images, stale detection, and translation metadata updates.
`ProjectEvaluator`	`co_op_translator.core.project.project_evaluator`	Finds translated Markdown pairs, evaluates translation quality, and reads confidence metadata for low-confidence repair workflows.
`ReviewRunner`	`co_op_translator.review.runner`	Coordinates deterministic review checks across source files, target languages, and configured translation roots.
`ReviewTarget`	`co_op_translator.review.targets`	Describes a source root and the translation output directory reviewed for that root.
`LanguageFolderMigrator`	`co_op_translator.core.project.language_migrator`	Detects legacy alias language folders and prepares canonical BCP 47 folder migration plans.
`Config`	`co_op_translator.config.base_config`	Loads `.env` files and checks whether required LLM and optional Vision providers are configured.
`LLMConfig`	`co_op_translator.config.llm_config.config`	Auto-detects Azure OpenAI or OpenAI, validates required environment variables, and runs provider connectivity checks.
`VisionConfig`	`co_op_translator.config.vision_config.config`	Detects Azure AI Vision configuration and runs connectivity checks for image translation.