ipynb-translator

ipynb-translator is a VS Code extension for translating one or more Jupyter Notebook Markdown cells through an OpenAI-compatible Chat Completions API. It supports the familiar one-click translation flow and an optional RAG mode for terminology consistency across batches.

What it does

• Translate one selected Markdown cell or multiple selected Markdown cells in a Jupyter Notebook.
• Invoke it from the Command Palette, the cell title button, the notebook cell right-click menu, or Ctrl+Shift+T (Cmd+Shift+T on macOS).
• Skip selected code cells and insert the translated Markdown directly below each source cell.

The extension works with OpenAI-compatible endpoints. Cloud and localhost services use the same implementation; only the configured base URL, model name, and optional API key differ.

Translation modes

Default mode: current batch translator

ipynbTranslator.rag.enabled is false by default. In this mode the existing behavior stays intact:

• One selected Markdown cell uses the normal text-only response protocol.
• Multiple selected Markdown cells use one request.
• No glossary is read, no Translation Memory is read or written, and no Embedding request is sent.

Optional RAG mode: Translation Memory

When RAG is enabled, the selected Markdown cells become one batch translation task:

selected source cells
  → per cell: exact terminology + structural context + BM25 / dense retrieval
  → one augmented JSON batch Chat request
  → validate every output ID and atomically update the Notebook
  → persist successful source/translation pairs as Translation Memory

Each source cell receives its own enhancement context, but the extension still sends just one structured Chat request for the whole selection—even for a single selected Cell in RAG mode. Embedding inputs are batched internally in groups of at most 10 automatically.

Persistent memory is stored outside the Notebook in VS Code’s extension-private storage. It is not shown in the Notebook or the extension UI, and contains source text, translations, target-language metadata, and cached Float32 embedding vectors.

Consistency pipeline

RAG mode combines four intentionally small, local components:

1. Exact glossary matching. Entries that literally occur in the current source Cell become hard terminology constraints. Latin terms use boundaries and overlapping phrases use longest-match priority.
2. Translation Memory retrieval. Historical bilingual Cell pairs are searched by BM25 and, when configured, dense Embedding similarity.
3. RRF fusion and hierarchy. BM25 and dense ranks are combined with reciprocal-rank fusion. Current-Notebook memories are selected first; Workspace memories fill remaining slots only when needed.
4. One augmented batch prompt. Exact terminology has higher priority than retrieved examples. Related terminology, historical pairs, the nearest heading, and adjacent source Markdown Cells are reference data—not instructions.

The memory is isolated by target language. A source/translation pair is stored only after the complete batch has passed output validation and the Notebook edit succeeds. Re-translating a tagged source Cell updates its paired translation in place instead of inserting another duplicate Cell.

If an Embedding service is not configured or fails, RAG degrades to exact glossary matching, BM25, and structural context; Normal translation is not blocked.

Configuration

RAG-specific settings:

Both endpoints accept a base URL with or without /v1; the extension only removes trailing slashes before appending the endpoint path. API keys remain ordinary VS Code Settings fields by design and are never copied from Chat to Embedding settings automatically.

Glossary

Run Jupyter Translator: Open/Create Translation Glossary in a workspace to create or open the configured file:

{
  "version": 1,
  "terms": [
    {
      "source": "gradient descent",
      "target": "梯度下降",
      "aliases": ["gradient-based descent"],
      "note": "机器学习优化算法"
    }
  ]
}

source and target are required. aliases and note are optional. A normalized source term that maps to conflicting target translations is ignored with a diagnostic rather than becoming an ambiguous hard constraint.

Translation memory commands and human edits

• Open/Create Translation Glossary opens the workspace glossary.
• Clear Current Notebook Memory removes only that Notebook’s external memory after confirmation.
• Clear Workspace Memory removes the external workspace memory after confirmation.
• Rebuild Memory Embeddings rebuilds cached source embeddings in batches of 10.

In RAG mode, saving an edited generated translation writes that human revision back to its Translation Memory entry. Editing only the source marks the old memory stale until it is translated again (or source and translation are saved together). Removing either tagged Cell removes the corresponding external memory. Clearing memory does not delete Notebook content。

Notes

• Translation Memory is capped at 500 entries per storage scope, favoring recently updated or retrieved entries.
• Embedding vectors are reused only when the Embedding base URL, model, and optional dimensions match the stored fingerprint. Old vectors remain eligible for BM25 until you run Rebuild Memory Embeddings.
• A standalone Notebook without a workspace uses isolated global storage and does not fall back to other Notebook memories.