eduKate Singapore

VIEW THIS AS

Auto mode follows the Route Engine until you choose a viewpoint.

YOU ARE HERE

ROUTE CHECK

CONNECTED TO

WHAT NEXT

Use the canonical route for this room, or HELP if you are unsure.

Next useful routeCanonical hubHELP

How People Translate Quickly | Jupyter Notebook Lesson QA: Translate Markdown Without Changing Code or Results

—

by

eduKate Asia

Suggested slug (not created): how-people-translate-quickly-jupyter-notebook-lesson-markdown-qa Reader job: Create a readable target-language version of a teaching notebook while keeping its executable computation, displayed evidence and instructional sequence trustworthy. Boundary: This article is about the instructional narrative of .ipynb lessons, not translating Python language keywords, building a full multilingual software application, or changing the scientific experiment.

A teacher searching how to translate a Jupyter notebook has a peculiar problem. Much of the lesson is made of ordinary sentences in Markdown cells, yet those sentences sit beside executable code, displayed tables, mathematical expressions, interactive widgets and cached outputs. A good Jupyter notebook localization workflow lets learners read the explanation in their language without changing the data analysis or making the computation appear to prove a different conclusion.

People also search for translate ipynb Markdown cells, multilingual Jupyter notebooks, and JupyterLab lesson translation. The useful distinction is between narration and evidence. Narrative prose can be translated; code and generated results require deliberate preservation or a separately authorized software-localization project. When a heading says “the average increases” but the unchanged graph shows a decrease, a visually polished lesson has become misleading. The translator’s first duty is to keep language and evidence aligned.

This guide is a practical method for educators, university tutors, curriculum writers and translators. It explains how notebooks are structured, what to translate, which tokens to protect, how to check links and formulae, and when a lesson needs subject review. It uses worked examples and a safe delivery workflow. The objective is not to finish the file by treating all JSON text as prose; it is to make a second-language notebook that teaches the same concepts and still represents the same computational evidence.

Quick answer: translate the lesson layer and verify the evidence layer

A Jupyter notebook is a structured JSON document, not a Word page. It commonly contains a list of cells. Markdown cells carry explanatory writing. Code cells carry source instructions, execution counts and outputs. Metadata carries information about the notebook or particular cells. A translation can often be confined to designated Markdown prose while leaving code, outputs, execution counts, media identifiers, and metadata stable. However, even when no code changes, the teaching may need additional care because prose refers to variables, labels, graphs and numerical results that remain in the source language.

The safe sequence is: establish a frozen source; inventory cells by type; identify translatable Markdown spans; protect equations, code fences, links and references; translate for the learner’s level; render and compare output; validate the notebook’s format; and conduct a subject-review pass on claims that cite results. If a graph title is generated by Python, changing its visible language is a code-output localization task, not something that happens automatically because a nearby caption was translated. Record that distinction so students are not led to expect a fully localized chart from a partially localized notebook.

1. Start with the learner’s real task

Imagine a Secondary student opening a notebook that introduces means and medians. The learner is expected to read a short explanation, run a Python cell, inspect a list of values, compare the mean with the median, and answer a reflection question. Translating the paragraph is helpful only if the student can still follow the complete learning route. A technically intact .ipynb file may be unusable if the target instructions refer to a button name the learner cannot locate, or if a term in the question differs from the graph label without an explanation.

Write a one-sentence outcome before translation: “After reading the target notebook, the learner can run the given cells, identify the two statistical measures and explain why an extreme value affects them differently.” That outcome guides terminology and content priorities. If the target language uses a familiar school term for median, choose it consistently across the introduction, interpretation and exercise. If learners will encounter English library names such as pandas in code, explain the relationship once instead of pretending the library name has been translated.

The audience matters as much as the subject. A notebook for a university research lab can tolerate terms that would obstruct a young beginner. A class using English Python keywords but Malay explanations may benefit from bilingual first mentions of certain terms. A translator should not silently convert all terminology to the most formal dictionary entries without considering what the student needs to recognise when working through code and school questions.

2. Understand the notebook’s cell model before extracting text

According to the Jupyter notebook format, a notebook contains top-level metadata, version fields and cells. Cells may be Markdown, code or raw cells; code cells include input, execution details and possibly output records. Their contents are not interchangeable. A Markdown cell may contain a heading, a mathematical formula, a hyperlink and prose in one text field. A code cell may contain a human-readable comment and a quoted string, but that does not make it safe to pass the entire cell through translation. Changing one string inside code can affect assertions, file paths, comparisons and plotted labels.

Take an inventory that records each cell’s position, type, unique identity if present, source length, and special content. Useful flags include LaTeX math, fenced code blocks, images, HTML, interactive components, embedded data, external URLs and references to outputs. This inventory helps choose the smallest safe scope. A notebook with ten plain prose Markdown cells is a different job from one that alternates equations, code and output after every sentence.

Do not rely solely on a text search for English words. A cell source can be represented as text or an array of lines in serialized JSON, and newline handling matters. Read through a notebook-aware library or a tested parser instead of applying unbounded find-and-replace to the raw file. Preserving the structure is how you avoid corrupting JSON punctuation while changing an ordinary teaching sentence.

3. Separate four kinds of text that look similar

The first category is instructional prose: explanations, learning objectives, introductions and reflection prompts. It is normally translatable. The second category is literal notation: Python syntax, mathematics, units, identifiers and API method names. Those items usually remain stable. The third is content generated by code: graph titles, dataframe labels, console messages, notebook widget labels and error text. Translating them may require editing the program or rerunning it, which needs a separate specification. The fourth is interface language provided by JupyterLab or the browser; that belongs to application localization, not to the notebook file.

A teacher may ask, “Please translate everything the student sees.” That request is understandable but too broad for safe execution without classification. A notebook can display an English label from a CSV file loaded at runtime, a hard-coded Python string, a Markdown heading and a Jupyter toolbar. These require different owners and methods. A rapid workflow becomes possible only after naming the layer each visible phrase belongs to. Otherwise a translator may spend hours editing prose while the most important English diagram labels remain generated elsewhere.

Create a scope note listing which categories are included and which are explicitly excluded. For example: “Translate Markdown explanations and exercise instructions; do not change code, data, output images or the JupyterLab interface. Flag generated English axis labels for a later chart-localization pass.” That note protects readers from a misleading promise of total translation and protects the original notebook from accidental functional edits.

4. Work through a simple statistical lesson

Consider a source Markdown instruction: “Run the next cell and compare the mean with the median. Then add the extreme value and explain what changes.” The next code cell calculates both measures from [2, 3, 3, 4, 8], then appends a much larger value. A good target version preserves the two operations and the comparison task. It must not turn “compare” into “calculate only,” or “add the extreme value” into “remove the outlier.” Both errors would redirect the student toward a different reasoning exercise.

Before translating, calculate the conceptual relationship from the supplied data. The initial mean is 4, and the median is 3. With a further value of 80, the mean increases markedly while the median changes much less. The target text should direct attention to this contrast and should not assert an exact post-change statistic unless it has been verified against what the code actually prints. Even an experienced translator can accidentally write “median stays constant” when the exact result depends on the sample and the convention used. The output, not intuition, determines the correct claim.

After translation, a bilingual tutor reads the prompt without the original beside it and predicts the learner’s action. The tutor should run the existing cell, inspect both statistics and explain sensitivity to an extreme value. If the target suggests writing new Python code or interpreting the wrong plot, revise the wording. This is a better comprehension test than checking whether every English phrase has a target-language counterpart.

5. Protect mathematical expressions without obscuring their meaning

Jupyter Markdown often uses LaTeX-like notation between dollar signs for formulas. An expression such as $\bar{x}=\frac{\sum_i x_i}{n}$ contains symbols, delimiters and command names that control mathematical rendering. A translation system may interpret \frac as a word-like token or accidentally change braces while reformulating the explanatory sentence. Do not allow that. Keep the mathematical expression intact unless a qualified mathematics editor has approved a different but equivalent representation.

The prose around the formula should explain the same relationship. If the source says that the numerator sums values and the denominator counts them, those roles cannot be inverted. Mathematical notation is compact precisely because each symbol carries a stable relationship. It is possible to translate the words while losing the explanation’s logic, especially when a target language reverses phrase order. A final reviewer should compare the target description with the displayed equation, not only with the source sentence.

An accessible explanation can be more helpful than a literal gloss. For beginners, “Add all the values, then divide by how many values there are” may teach the mean more clearly than a technical phrase copied from a formal paper. However, the translator should not lower difficulty arbitrarily if the lesson is preparing learners to use professional statistical vocabulary. Choose language according to the learning objective and retain the exact symbols students will see in code and examinations.

6. Preserve fenced code and inline code precisely

Markdown can contain inline code such as df.head() and fenced code blocks that show commands. These are not automatically executable notebook code cells, but they often instruct a learner exactly what to type. If a translator changes read_csv to a natural-language equivalent, the explanation becomes unusable. Preserve identifiers, punctuation, capitalisation and argument names. Translate the surrounding imperative, not the command. If an inline example contains a clearly translatable string argument, escalate it for code-aware review instead of assuming it is a harmless phrase.

Suppose the source says, “Call df.describe() to inspect the numerical summary.” A target language may express the instruction in a different word order while keeping df.describe() exactly. The source may also include df['height_cm']. That bracket expression names a specific dataframe column; changing the spelling can cause a runtime KeyError. Because the column name looks like ordinary English, it is a common point of failure for broad machine translation.

A reliable extraction system masks code spans before translation and restores them afterwards, then checks equality. The check should distinguish literal protected fragments from ordinary natural-language content. A reviewer can verify that the target reads naturally while every code token survives. If a protected expression must genuinely change as part of a multilingual dataset release, record it as a new technical task with code and data tests, not as an unnoticed extension of prose translation.

7. Translate instructions without changing operational order

Notebook lessons are procedural. “Run this cell before updating the parameter” differs from “update the parameter before running this cell.” Word order can change in translation, but the sequence of learner actions must remain intact. Conditions matter too: “Only run the next cell if the data file has downloaded” is not equivalent to “Run the next cell after downloading the file,” because the second wording may imply that downloading is guaranteed or sufficient. Each conditional is part of the classroom’s task management.

A useful method is to write an action trace for every multi-step instruction: open file → execute setup cell → inspect table → change one parameter → rerun chart → answer question. Translate against that trace. It is especially valuable when the notebook mixes teacher demonstrations and student exercises. Learners should know which cells they are permitted to modify and which should remain as reference examples.

When translating polite instructional language, prioritise operational clarity over rhetorical similarity. A target-language class may expect a more direct imperative than English “You may wish to try.” If the original invites an optional experiment, make it sound optional. If a safety or dependency constraint is mandatory, make it sound mandatory. A translated notebook that loses those distinctions can lead to missing data, failed imports or learner frustration even though every individual sentence appears correct.

8. Deal carefully with output claims and stale execution state

Jupyter notebooks can store outputs from previous code execution. A displayed chart may be stale relative to the current code if the notebook has been edited without rerunning it. This is not a translation problem at first, but translation can make the inconsistency harder to spot. A translator may infer a conclusion from the visible chart while the code would now produce something else. Always record whether outputs are trusted reference artifacts, reproducible results, or unverified cached material.

If the project has permission to execute code in a controlled environment, a qualified maintainer can verify results before translation. But do not run untrusted notebooks merely to see whether they work. Code can read files, send data over networks or modify the environment. For a translation-only project, it may be safer to leave execution unchanged and label results as “not rerun in this translation review.” A trustworthy lesson should never claim that translation QA verified computational correctness if no such check occurred.

In a long data-science lesson, execution order can matter. A variable may have been defined in a cell that appears later on screen but was run earlier in the author’s session. An editor translating headings can accidentally make the sequence sound more deterministic than it is. If the teaching instructions presuppose top-to-bottom execution, ask the notebook owner to verify that it runs from a clean kernel. Keep this as a technical release gate, not as an extra burden silently assigned to the translator.

9. Charts may speak a different language from their captions

A notebook can contain a chart whose axis labels are generated by code and a Markdown paragraph that describes the chart. Translating the paragraph alone creates a bilingual figure. That can be acceptable if the course deliberately teaches English technical labels, but it should not happen by accident. Note every graph title, axis label, legend, series name and annotation, and decide whether it must remain English, be glossed once, or be localized through a separate code-approved change.

Imagine a graph titled “Average Daily Temperature” with an x-axis called day and a y-axis called temp_C. A target paragraph could naturally explain temperature over time without rewriting the identifiers. But if the paragraph states that the y-axis shows rainfall, it becomes factually wrong. Check each translated description against the actual chart. Translators should not invent labels that are absent or describe trends with greater certainty than the plot supports.

For multilingual instruction, a short glossary just below the figure may be more robust than rewriting plotting code. It can explain that the code column temp_C stores temperature in degrees Celsius, while the target lesson uses the preferred local term for temperature. This approach preserves reproducibility and still makes the evidence intelligible. It is particularly useful when the class will share a dataset with English column names throughout later lessons.

Markdown uses syntax such as [visible label](destination) for links. Usually the visible label is translatable while the target URL or anchor should remain stable unless the linked resource has an approved localized equivalent. A translation system that rewrites the URL because it contains English words can create dead references. Relative links to images and course resources are especially fragile because they depend on repository layout.

Heading translations can also affect anchors generated by renderers. A source link to #interpreting-the-chart may stop navigating correctly if the localized heading produces a different anchor. JupyterLab, notebook viewers and static exporters can use different rules for headings and anchors. Do not assume automatic fragments are portable. Test important internal navigation in the actual delivery environment. Where possible, prefer a stable anchor strategy approved by the maintainer, and document how translated headings are linked.

A worked case: an exercise says “Return to the Data cleaning section,” with a Markdown link pointing to a heading in the same notebook. The translator localizes the visible instruction and heading but leaves the old fragment unchanged. The link now fails. The text passed spelling review but did not pass navigation QA. This is easy to prevent with a link inventory and a click test on every internal reference. The lesson is that a notebook is a navigable document as well as an executable one.

11. Alternative text and embedded images need their own review

Images in Markdown may be linked by relative path, attached to the notebook, or embedded through data references. Some Markdown image syntax includes alternative text that supports accessibility; other images may be generated outputs with their own metadata. The translation team should not treat these uniformly. Translate learner-facing alternative descriptions where permitted, preserve attachment identifiers and relative paths, and verify that images still render after saving the target notebook.

For a diagram that explains the steps of a machine-learning pipeline, the words printed inside the graphic may still be English. A target-language alt description should not pretend that the graphic has been localized. It can describe the relationships shown, including original labels when necessary to help students find them. If the image contains key scientific quantities, copy them accurately. Do not smooth away an uncertainty symbol or replace a label with a different technical term merely to shorten the sentence.

Accessibility also applies to equations and tables. If a lesson communicates its argument only through colour, translating the prose will not automatically create an equivalent experience for a colour-blind learner. An editorial review can flag such issues for the course owner without altering the figure. The goal of the translation project is not to claim that every pre-existing accessibility issue has been solved; it is to avoid introducing new barriers and to document those that materially obstruct the target lesson.

12. Handle tables and data values as evidence

Markdown tables and embedded HTML tables may mix translatable headings with numerical values. Translate header labels only after identifying whether they are narrative labels or literal names used later in code. Do not rearrange columns simply because target text would read better in a different order. A student may be asked to interpret the second column specifically, and the prose may refer to it by position. If the column order changes, that cross-reference must be updated and verified.

Consider a small table: Learner | Hours studied | Score, followed by a scatter plot using hours and score. Localizing the displayed Markdown headers may be harmless if the table is independent. But if later code loads the same headings as CSV column names, changing the source file or displayed labels without changing the data pipeline can create confusion. Separate “the words learners read in the lesson” from “the schema used by the program.” A glossary can bridge both without breaking code.

Do not localize raw measurement values merely to satisfy typography. A value of 1.25 inside code or a dataset is not equivalent to the string 1,25 unless the parser and data contract explicitly support that representation. In prose, a locale may use a different decimal mark or grouping convention, but the converted display should preserve magnitude and unit. For a learning task, consistency between displayed values and calculation results is more important than superficial typographic uniformity.

13. Research terms that cross teaching and programming

Many notebook terms have two lives. “Model” can refer to a mathematical abstraction, a fitted predictive algorithm, or a demonstration example. “Class” can mean a school cohort or a programming construct. “Feature” may be an ordinary characteristic or a variable supplied to a model. A general bilingual dictionary may list valid translations for all these senses without telling a translator which one the notebook uses. Read the surrounding code and lesson objective before settling on a term.

Create a compact concept note: source term; sense in this notebook; learner level; target expression; first-use explanation; and protected code spelling if relevant. For example, the target prose may use a school-appropriate term meaning “variable,” but the code still contains a column called feature_1. Explain the relationship once instead of making the target language perform an impossible one-to-one mapping. This reduces recurring confusion without requiring learners to memorise a software engineer’s terminology before they understand the mathematics.

A strong QA question asks, “Could a student explain the target term while pointing to the relevant code and output?” If not, the glossary may be linguistically correct but pedagogically ineffective. A second QA question asks whether the target makes distinctions the source intended to leave open. Over-translation can be as misleading as under-translation when it turns a broad word into a specialised concept too early in the lesson.

14. Plan a deliberate treatment of exercises and hints

Exercises inside notebooks often alternate an instruction, a blank code cell, a hint, and a model answer. The translation must preserve which information is available to the learner before they attempt the task. If a target hint reveals the entire answer, the exercise no longer tests the intended skill. If a translated prompt accidentally includes a variable name that was introduced only in the solution, learners receive a clue they did not have in the source version.

Trace each exercise as a sequence: what the learner knows, what the learner must do, what help is optional, what counts as a correct response, and where feedback appears. Translate instructions, then review them against the solution code or teacher notes without exposing those materials in the learner version. A bilingual subject reviewer should attempt at least the major exercises using only the target prose. If the reviewer must consult the source to understand the task, the target lesson is not independently usable.

Be cautious with culturally familiar examples. Replacing a dataset about rainfall with one about exam scores changes more than the nouns: it may alter the variables, ethical sensitivities, distribution shape and plots. Unless a new dataset and complete lesson have been approved, translate the explanation of the existing dataset. In science teaching, intellectual fidelity is more important than a superficially local setting.

15. Handle notebooks with multiple languages honestly

A bilingual notebook can be designed as two parallel files, language-specific Markdown cells in one file, or one notebook that loads translations dynamically. Each model brings trade-offs. Separate files are straightforward for readers but require synchronized maintenance. Parallel cells may make the notebook long and confusing unless presentation carefully controls visibility. Dynamic localization can be elegant but may involve widgets or extensions that are not available in every learning environment. The project should not adopt a complex architecture merely because the word “multilingual” sounds ambitious.

For most small educational releases, one controlled source plus a clearly named target derivative is an understandable choice. Preserve a mapping of cell identities or stable lesson sections so that a later source update can be located in the translation. Treat updates to code and data differently from updates to prose; if the underlying computation changes, revalidate every target explanation that discusses the result. The target notebook should include a visible revision note if it is used independently from its source.

Students should never have to guess which language governs a particular instruction. If English remains in code, graph labels and library messages, explain that boundary near the beginning. A short sentence saying that code identifiers are preserved for reproducibility can prevent confusion. It also teaches an important transfer skill: natural languages and programming languages serve different functions, and translation changes the first without automatically rewriting the second.

16. Why speed comes from extraction discipline

The apparent shortcut is to open .ipynb as text, translate every English phrase and save. That creates avoidable damage. A more efficient method loads the notebook through nbformat or another notebook-aware system, extracts allowed Markdown segments, protects literals, and writes only those segments back. Afterward it validates the notebook schema and compares protected fields against the source. This makes the mechanical part repeatable. If the notebook contains 200 code cells and 80 explanatory cells, there is no reason to expose all 200 code cells to a general-purpose translation process.

A good extraction manifest can list cell position or stable ID, source checksum, protected spans, translation status, reviewer and target checksum. It should not create a false impression that the cell position will stay stable forever. New source versions may insert cells, so use a combination of IDs, context and content matching when reconciling revisions. Reviewers should see enough surrounding code and outputs to understand the meaning even if only Markdown prose is sent for translation.

The cost saved by extraction is only valuable if it does not shift risk elsewhere. If the translator receives “The following line shows the result” without the result, the source has been over-segmented and stripped of meaning. Provide screenshots, output descriptions or a read-only notebook view as context. Effective translation is selective editing with complete contextual knowledge, not blind isolation of text strings.

17. A practical three-gate QA sequence

Gate one — structural integrity. Parse the .ipynb file, validate it against the notebook format, and compare cell count, types, key metadata, code sources and outputs with the source. An approved language-note metadata change may be acceptable, but record it. Unexpected changes to code or output should block the release. A file that still has the .ipynb extension but invalid JSON is not a completed notebook translation.

Gate two — rendered experience. Open the target in the intended JupyterLab, Notebook, Jupyter Book or LMS environment. Inspect math rendering, Markdown formatting, links, table wrapping, images and cell order. Check that longer target paragraphs do not bury critical instructions under enormous headings or collapsible blocks. If the course uses mobile devices, inspect the narrower layout. A technically valid notebook can still be hard to read.

Gate three — learning alignment. Have a bilingual subject tutor use the target version to complete selected tasks and explain the output. The tutor should check that instructions refer to actual variables and plots, mathematical relationships match the evidence, and reflection prompts test the same reasoning. A good final question is “What would a student do differently because of this wording?” If the answer differs from the source task, investigate before release.

18. Worked end-to-end scenario: a classroom graphing lesson

A teacher shares a notebook with 24 cells: nine Markdown explanations, ten code cells and five code outputs. Students are learning how to plot a linear relationship and interpret gradient. The source opens with definitions of independent variable and dependent variable, shows Python using matplotlib, and asks students to explain what a steeper line means. The notebook is to be translated for a bilingual class while preserving the teacher’s tested computations.

The translator inventories cells and sees that two Markdown cells contain inline code; one has a LaTeX expression; two link to a locally stored figure. The teacher approves translation of headings, explanations, task instructions and figure descriptions but not changes to code or the dataset. A termbase is agreed for “slope,” “gradient,” “axis,” “variable” and “rate of change.” The extraction process protects plt.plot(x, y), x_values and the formula while passing explanatory prose for language review.

A first draft introduces a subtle error: a target sentence says a steeper negative gradient means a greater numerical value. A bilingual mathematics tutor notices that “greater” is ambiguous because -5 is numerically less than -2 while its magnitude is greater. The repair explicitly distinguishes sign from magnitude and asks students to compare line steepness using the absolute value of the gradient. The notebook’s code never changed; the pedagogy needed more precise language. A good translation review found that problem before learners did.

During rendering QA, one relative image path fails because the translated notebook was moved into a new folder while its image stayed in the source folder. The team restores the expected directory structure instead of rewriting the image reference blindly. Later, a cross-reference to “the graph above” becomes confusing because a longer translated paragraph separates the sentence from its graph. The editor changes the prose to identify the graph by a stable descriptive phrase. The final target file passes format validation, loads in the teaching environment, and preserves code and outputs byte-for-byte or by an approved semantically equivalent comparison.

The teacher then asks a learner to perform the exercise without viewing the English source. The learner runs the intended cells, recognises the plotted relationship and writes a correct interpretation. That is the release criterion. Language has changed, but the student still reaches the same mathematical idea through the same evidence.

19. Failure modes worth testing on every new batch

Failure: code identifiers were translated. The target contains a natural-language version of df['column'] and fails. Repair the protected-span extraction and compare code values with the source. Failure: cached output contradicts translated prose. The editor wrote a conclusion about a newly imagined figure. Repair the claim against the actual reference output and request computational verification where necessary. Failure: Markdown formatting breaks. A list is flattened or a code fence is dropped. Render before release and restore syntax.

Failure: links no longer navigate. Headings or resource paths were changed without corresponding reference updates. Click every internal link and a representative sample of external links. Failure: mathematical symbols are damaged. A backslash or brace was removed from LaTeX. Compare expressions and render them in the target environment. Failure: translation changes the learner task. “Observe” became “predict,” or “compare” became “calculate.” Have a subject tutor paraphrase the instruction and perform it. Failure: localisation promises exceed scope. A course advertises a fully translated notebook while diagrams and outputs remain English. Describe the boundary clearly and plan separate work where required.

Not every failure should be repaired by changing words. If a library prints an untranslated exception message, the appropriate route may be teaching support or software localization. If a dataset contains a misleading English category name, the owner may need a controlled data transformation. If the original experiment is scientifically wrong, a translator should flag it rather than quietly correcting it in one language. Correct ownership speeds repair because each issue goes to the person who can resolve it safely.

20. Protect reproducibility, provenance and learner trust

Educational notebooks often circulate as copied files. A translated file may be reuploaded to an LMS, emailed to a class or added to a public repository. Include a human-readable note identifying the source lesson, target language, translation revision, extent of translated content and whether code was rerun. Do not claim reproduction or validation beyond the tests actually performed. If a notebook contains third-party text or images, the right to translate and redistribute them must be checked separately from whether the file format allows editing.

Preserve the distinction between source authorship and translation authorship. A student should know when a translated explanation was added after the source experiment was written. If the source notebook is updated, the team needs to know which target explanations may now be stale. A small change log connecting cell section, old claim, new claim, reviewer and date can prevent contradictions in subsequent classes. Be especially careful when a subject tutor rewrites a scientific conclusion; that deserves the same evidence review as a new claim.

Privacy and security also matter. Notebooks sometimes contain access tokens, example credentials, local file paths or personal data accidentally saved in outputs. The translation process should not send such data to an external tool without permission. Masking sensitive content for translation is useful, but maintain enough context for the translator to understand the sentence. The cheapest translation is not a good result if it creates a new data disclosure.

21. A compact classroom release checklist

Start with a frozen source and a clear statement of the target learner, skill and permitted changes. Inventory cells, references and media. Translate only approved Markdown prose and other expressly authorized human-facing material. Keep code syntax, data, IDs, outputs and dependencies stable. Review mathematical vocabulary at the course’s level. Confirm that target instructions preserve sequence, conditions and permissions. Render the notebook and inspect links, headings, equations, tables and images. Validate the .ipynb structure. Conduct a bilingual learning test against outputs. Record known untranslated surfaces honestly.

If a tool generates a report showing that every protected code cell is unchanged, the reviewer can devote attention to meaning. But do not substitute that report for reading the lesson. Code invariants detect code drift, while subject reviewers detect conceptual drift. Use both. For high-stakes or assessed material, the institution should establish a stronger testing and sign-off policy than for optional practice notes. A translated lesson should not be released to learners merely because it passed a syntax validator.

After release, collect concrete learner reports. “I cannot run cell 7” is a different problem from “I do not understand the word translated as gradient.” Route the first to environment or notebook maintenance and the second to instructional terminology review. Keep source and target versions connected so a good fix can be considered for both. Translation is successful when learners can use the explanation to reason with the evidence, not when a percentage of English strings has disappeared.

22. Transfer: teach students the difference between words and operations

The method extends to R Markdown, Quarto and computational textbooks, although their file structures differ. The transferable principle is to protect executable truth while adapting the language of instruction. A program’s variable names and a learner’s conceptual vocabulary are related but not identical. A chart result and a caption are related but independently editable. A notebook’s order of operations is part of the learning path. Good localization therefore requires more than text fluency, yet it does not always require rewriting code.

There is a useful educational lesson hidden in this work. Students learn that the same mathematical concept can be named differently across languages while the computation remains stable. They see that clear definitions and carefully traced operations matter more than memorising a single English phrase. A bilingual notebook can help students cross from natural-language understanding to symbolic, computational reasoning. That transfer is valuable well beyond a single lesson in Python.

Summary

Translate the explanation, preserve the evidence, and test the learner route. Jupyter notebook localization works when Markdown becomes accessible without corrupting code, outputs or mathematical meaning. Faster production comes from notebook-aware extraction, protected spans, a terminology map and targeted bilingual review. File validity, rendering quality and educational equivalence are three separate gates. A strong target notebook passes all three and describes any remaining English surfaces accurately.

Frequently asked questions

Can I translate a notebook by opening the .ipynb file as JSON?

You can inspect the file as JSON, but editing it manually is error-prone because a notebook contains metadata, cell types, line representations and possibly large output records. Prefer a notebook-aware parser or library, translate only approved fields, then validate the result with the notebook format. Do not treat every quoted English string as instructional prose.

Should I translate Python comments and printed strings?

Not automatically. Comments and strings appear inside code cells, so translating them changes the executable source even when the comment itself is not executed. Printed strings may be compared by tests, used in charts or expected by a tutorial. Handle code-cell localization as a separate, approved change with technical tests. If the request is restricted to Markdown translation, leave code unchanged.

How can I tell whether outputs are stale?

A translation-only review usually cannot establish this from appearance alone. Record whether outputs were verified against a clean execution, and consult the notebook maintainer if a conclusion depends on them. Do not run untrusted notebooks in an unrestricted environment, and do not tell readers results were reproduced unless they were.

What happens to equations in target-language Markdown?

Protect the mathematics markup and render it in the target environment. The surrounding explanation may change order and vocabulary, but the operations, variables and assumptions must remain coherent. Subject review is especially important when the same word has a technical and everyday meaning.

Is translating only Markdown enough for a fully multilingual lesson?

Not necessarily. Code-generated graph labels, datasets, widgets, image text, outputs and the Jupyter interface may remain in another language. Markdown-only localization can be a useful, clearly labelled product, but full localization needs an inventory and potentially other owners. Avoid overpromising completeness.

Should a translated notebook have separate code execution results?

Not solely because the prose changed. If code and data are unchanged, changing outputs can introduce unnecessary differences. If authorized localization requires changing chart labels or generated strings, the maintainer must decide how to regenerate and verify outputs safely. Treat this as a controlled technical change rather than a side effect of translation.

Can a beginner use a notebook whose code is in English and explanation is in another language?

Often yes, because Python keywords and library method names are technical syntax rather than English prose. Explain that distinction at the start, teach the meaning of important identifiers, and ensure instructions clearly map to the unchanged code. The aim is comprehension and reproducibility, not disguising programming syntax as natural-language text.

What is the final acceptance test for a translated lesson?

Have a representative learner or bilingual tutor use the target notebook to perform the intended tasks and accurately interpret the unchanged evidence. Pair that with notebook validation, protected-code comparison and rendered-content QA. A target text that reads well but leads the student to perform the wrong operation is not finished.

Sources and useful internal routes