This document provides a high-level technical overview of DocstringTranslation.jl, a Julia package that automatically translates Julia documentation (docstrings) and Documenter.jl pages using Large Language Model (LLM) services. This page covers the system's architecture, core components, and integration points with Julia's documentation infrastructure.
For installation and quick start instructions, see Installation and Quick Start. For detailed information about specific subsystems, see Core System Architecture, Caching System, and Documentation Integration.
Sources: README.md1-160 docs/src/index.md1-252
DocstringTranslation.jl intercepts Julia's documentation system to provide on-demand translation of docstrings and documentation pages. The package operates as a middleware layer between Julia's Base.Docs module (for docstring retrieval) and external translation services (currently OpenAI API). Users invoke the @switchlang! macro to activate translation for a specified target language, after which all documentation requests are transparently routed through the translation pipeline.
The system maintains a persistent cache of translations to minimize API calls and costs. Cached translations are organized by module name, version, and content hash, enabling efficient reuse across sessions and version upgrades.
Sources: README.md6-8 docs/src/index.md1-4 src/DocstringTranslation.jl1-38
Diagram: Core system architecture showing code entities and their relationships
This diagram illustrates the key code entities in DocstringTranslation.jl and how they interact. The main entry point is the @switchlang! macro defined in src/switchlang.jl which overrides methods in Base.Docs.parsedoc and Documenter.Page. When documentation is requested, these overridden methods intercept the request and route it through the translation pipeline implemented in src/openai.jl The caching layer in src/scratchspace.jl checks for existing translations before making API calls. Utility functions in src/util.jl support both the translation and caching operations.
Sources: src/DocstringTranslation.jl1-38 README.md1-160
| File | Primary Exports/Functions | Purpose |
|---|---|---|
src/DocstringTranslation.jl | Module definition, @switchlang! (re-exported) | Main module; orchestrates includes and exports; defines global refs DEFAULT_LANG, TRANSLATION_CACHE_DIR, DOCUMENTER_TARGET_PACKAGE |
src/switchlang.jl | @switchlang! macro | Language switching engine; overrides Base.Docs.parsedoc and Documenter.Page constructor |
src/openai.jl | translate_docstring_with_openai, translate_md! | OpenAI API integration; handles translation requests and prompt construction |
src/scratchspace.jl | get_cached_translation, store_cache | Cache management; reads/writes translations to persistent storage |
src/util.jl | hashmd, postprocess_content, prevminor, insertversion | Utility functions for hashing, content processing, and version handling |
Sources: src/DocstringTranslation.jl25-29 Project.toml1-33
Diagram: Translation workflow showing function call sequence
This sequence diagram traces the execution flow from user invocation to translated output. The @switchlang! macro sets the DEFAULT_LANG ref src/DocstringTranslation.jl13 and overrides Base.Docs.parsedoc. When a docstring is requested via @doc, the overridden method generates a hash using hashmd() and queries the cache via get_cached_translation(). On cache miss, translate_docstring_with_openai() makes an API call, and the result is stored via store_cache().
Sources: src/DocstringTranslation.jl13-23 README.md55-128
Diagram: Dependency relationships with external packages
Dependency Details:
parsedoc src/switchlang.jlsha256 for content hashing src/DocstringTranslation.jl5 used in hashmd() src/util.jl@get_scratch! src/DocstringTranslation.jl8-35Page constructor override for documentation generation src/DocstringTranslation.jl9Version Compatibility:
Sources: Project.toml6-23 src/DocstringTranslation.jl3-11
The package maintains three global mutable references that control runtime behavior:
| Reference | Type | Purpose | Default Value | Setter Function |
|---|---|---|---|---|
DEFAULT_LANG | Ref{String} | Target translation language (ISO 639-1 code) | Unset until @switchlang! | @switchlang! macro |
TRANSLATION_CACHE_DIR | Ref{String} | Filesystem path for translation cache | ~/.julia/scratchspaces/.../translation | switchtranslationcachedir!() |
DOCUMENTER_TARGET_PACKAGE | Ref{Dict{Symbol,Any}} | Package metadata for cache organization | Dict(:name=>"julia", :version=>VERSION) | switchtargetpackage!() |
These references are defined at src/DocstringTranslation.jl13-15 and initialized in the __init__() function src/DocstringTranslation.jl32-36 The configuration functions are defined at src/DocstringTranslation.jl17-23
Sources: src/DocstringTranslation.jl13-36
The translation cache is organized hierarchically to enable efficient lookups and version-aware fallback:
~/.julia/scratchspaces/d404e13b-1f8e-41a5-a26a-0b758a0c6c97/translation/
├── <module_name>/ # e.g., "Base", "LinearAlgebra"
│ └── <version>/ # e.g., "1.11"
│ └── <hash>/ # SHA256 hash of original content
│ ├── original.md # Immutable source content
│ ├── ja.md # Japanese translation (if requested)
│ ├── de.md # German translation (if requested)
│ └── ... # Other language translations
The cache directory structure enables:
.md filesprevminor() function src/util.jl checks previous minor versions if current version cache doesn't existExample Cache Path:
~/.julia/scratchspaces/d404e13b-1f8e-41a5-a26a-0b758a0c6c97/translation/
Base/1.11/Math/77be4ada26c623c913ebbdae5d8450a4dfe8f3cbf67837faac9d7193342d2bfe/ja.md
Sources: docs/src/index.md117-139 src/scratchspace.jl
Minimal Invasiveness: The package extends Julia's documentation system through method overriding rather than replacing core infrastructure. This allows existing documentation workflows to continue functioning normally when translation is disabled.
Lazy Translation: Translations occur on-demand when documentation is requested, not during package loading or precompilation. This minimizes startup time and only translates content that users actually view.
Persistent Caching: All translations are cached to disk using Scratch.jl, surviving across Julia sessions and reducing API costs. The cache is content-addressed (via SHA256 hashing), ensuring that identical docstrings are only translated once.
Version Awareness: The cache organizes translations by package version (major.minor), with automatic fallback to previous compatible versions via the prevminor() function. This allows translations to persist across patch version upgrades.
Transparent Integration: When the @switchlang! macro is not invoked, the package has zero runtime overhead. The method overrides only activate after explicit user configuration.
Manual Override Support: Users can manually edit cached translations by modifying the language-specific .md files in the cache directory. The system respects these edits and does not overwrite them.
Sources: src/DocstringTranslation.jl1-38 README.md1-160
The __init__() function src/DocstringTranslation.jl32-36 performs the following initialization steps when the package is loaded:
DOCUMENTER_TARGET_PACKAGE[] to Dict(:name=>"julia", :version=>VERSION), defaulting to Julia's standard libraryTRANSLATION_CACHE_DIR[] by calling @get_scratch!("translation"), which creates or retrieves the persistent cache directoryThe DEFAULT_LANG reference remains unset until the user invokes @switchlang!, ensuring that translation is opt-in.
Sources: src/DocstringTranslation.jl32-36