How do you translate an Adapt Learning Framework course into multiple languages while preserving its JSON structure, CSV translation exports, responsive HTML5 behavior and accessibility? Adapt course localization is a technical and instructional workflow. The framework stores language-specific learning data in course folders, provides documented translation export and import tasks and can use a Language Picker extension to present approved languages to learners.
This Adapt Learning localization guide explains `src/course` language directories, `course.json`, `config.json`, translatable fields in plugin schemas, Grunt CSV or JSON exchange, UTF-8 handling, translated assets, language selection, right-to-left presentation and multilingual builds. It is intended for developers, instructional designers and translators who need to produce professional multilingual training rather than simply replace English strings inside a web application.
The Adapt Framework’s official Course Localisation documentation, edited in March 2026, distinguishes exporting translatable text from exporting an entire course. It explains that fields must be marked translatable, that imported content depends on required plugins and that assets are not automatically copied or relinked. That distinction is fundamental: a structurally valid import can still leave a broken image, an untranslated accessible label or an assessment whose intended meaning has changed.
The answer in one minute
Start with a completed, tested master course and document its supported Adapt version and plugins. Identify which course JSON fields are translatable, export text through the supported Grunt tasks where appropriate, translate without altering identifiers or file structures, and import into target-language folders. Validate both the text and any locale-specific assets. Configure the default language and a Language Picker only for versions that actually exist, then build and test the multilingual output.
Think of a translated course as two linked systems: human meaning and runtime behavior. The human side includes instructions, feedback, examples and accessible descriptions. The runtime side includes identifiers, JSON syntax, plugin dependencies, asset paths, browser behavior, assessment logic and delivery records. A successful localization protects both. When something fails, identify which side is responsible before changing content at random.
The essential Adapt Framework concepts
The Adapt Framework is an open-source toolkit for authoring responsive HTML5 learning content. Its documentation describes delivery on a web server or through a SCORM-compliant LMS, with assessments, plugin-based interactions and multilingual support. A separate Adapt authoring tool can help nondevelopers build courses. However, the detailed command-line workflow in the Framework documentation is not automatically identical to every feature available in every authoring-tool installation. Confirm the environment before following a command.
The course structure distinguishes configuration from human-facing content. The Framework guide shows `config.json` at the course root and language-specific folders under `src/course/`, such as `src/course/en/`. The `course.json` file sits inside the language folder and supplies course-wide strings such as titles, button text and other shared values. Pages, articles, blocks and components carry additional content. Translators should understand that a course consists of many related JSON records, not one document.
Adapt’s documented export process draws on fields marked as translatable in a plugin’s `properties.schema`. This creates an important limitation: content that a custom plugin fails to mark for translation may not appear in exported files. A clean export therefore proves only that the currently declared translatable fields were extracted. Auditing custom components and interface messages is necessary before concluding that coverage is complete.
The documented Grunt export command can output CSV and other formats into a languagefiles directory. A CSV handoff contains structured rows corresponding to different content models, and the target importer relies on the relationship between IDs and translated values. Do not rename identifier columns or rely on a spreadsheet program that silently changes encodings, quoting or line breaks. A language professional may need a translation-friendly representation; a developer must protect the machine-readable contract.
Import creates or replaces target-language data according to the command options, but it does not install missing plugins. It also does not automatically copy and adjust every media asset. These facts separate text transfer from whole-course production. A translated project may be syntactically valid and still present an English illustration, a broken image path or an extension whose target-language label was not exported.
The Language Picker is an extension used to select among installed course languages; it does not perform translation. The configuration must reflect the actual language folders and a suitable default. A learner choosing a language should receive coherent content, not a half-built directory containing untranslated fallbacks. If change of language affects progress or tracking in a particular implementation, examine that behavior in a staging environment rather than assuming the toggle is harmless.
Localized themes and right-to-left presentation require attention beyond text. Adapt can set the HTML document’s language attribute, allowing language-specific styling such as CSS `:lang()` rules. But correct directionality and accessibility depend on the course, theme and components. A language code does not itself resolve visual arrows, mixed-script identifiers, screen-reader voices or information embedded inside media.
Worked example: localizing an open training course
Consider an Adapt course teaching incident reporting in a laboratory. The source includes a course title, shared instructions, pages describing evidence, an interactive sorting task and an assessment. It also contains a video with captions, a diagram of the reporting path, an image description for assistive technology and a custom plugin with a reusable warning component. The master English course works correctly in the browser and in a test LMS.
Begin by locating the actual source JSON and plugin configuration. Record the Adapt version and plugin dependencies. Inventory all human-facing values, including text in `course.json`, content model files, custom components, navigation controls, feedback and accessible labels. Where a plugin’s schema omits the `translatable` designation for a human-facing field, the developer should fix that coverage issue in the project’s supported process before the translation export becomes the main workstream.
Export approved text with the documented tools and provide the target-language reviewer with screen context, not just CSV cells. Preserve IDs, column relationships, special characters and UTF-8 encoding. Keep a clear source revision while files circulate. When the target files return, import them into the correctly named language folder, check that the relevant plugins remain installed and ensure that target JSON is valid.
Review the media separately. The diagram may need a new localized asset and a revised accessible description. The video may require a translated subtitle track and a different narration. Imported text does not automatically copy assets or correct paths, so explicitly check the references. A learning designer then runs the target-language version and verifies that every interaction teaches the same decision without confusing warnings or misleading feedback.
Configure language selection only for completed targets, build the intended languages and test the output on phones, desktops and in the destination LMS. The review is complete when the target-language learner can identify an incident, submit the correct report, explain an incorrect answer and receive a coherent completion result. A successful `grunt` command is technical evidence, not a substitute for that learning demonstration.
Thirty practical Adapt localization problems and solutions
1. Find the actual course root
What can go wrong. A translator receives a ZIP and assumes every JSON file is part of the text to translate. Editing build output instead of the source produces changes that disappear on the next compilation.
Practical response. Identify the project root and the authored source under `src/course`. Separate generated artifacts, configuration, content models and plugin code before any language edit.
Prove it works. Build the untouched project once and record which directories are generated. Future corrections should be applied to the authoritative source files, not only to a temporary output. An important principle follows from this case: tool success and learner success are different forms of evidence. A command can complete and a page can render even when an instruction is ambiguous. Ask what the learner must understand and what observable behavior would demonstrate that understanding, then choose a test that actually measures it.
2. Understand `config.json` versus `course.json`
What can go wrong. A developer puts translated button text inside a global configuration setting, while the framework expects it in the language-specific course data.
Practical response. Use `config.json` for appropriate project settings and language directories for localized course data such as `course.json`. Read the installed project’s documentation before moving properties.
Prove it works. Change one course-wide label in a test language and verify that the correct file controls the displayed string without affecting the source edition. Keep source authority visible. Translators can make language clear, while developers preserve runtime structure and subject experts approve factual or safety-critical changes. When these responsibilities blur, a well-intentioned technical repair may unintentionally rewrite the lesson. A short decision record protects both meaning and engineering integrity.
3. Map contentObject, article, block and component data
What can go wrong. A team translates page titles but misses the smaller blocks and components where the actual learner instructions appear.
Practical response. Inventory the hierarchy of pages, articles, blocks and components. Treat navigational titles, task prompts, answer feedback and accessibility metadata as separate functional content.
Prove it works. Follow one complete learner path and check a representative field at every level. A complete list of page titles is not a complete content inventory. Do not treat translation as a one-off migration. A course will receive new knowledge, revised examples, updated plugins and changing media. The team that records why a value belongs in a certain file makes future changes safer; the team that merely gets one build to pass leaves fragile work for the next maintainer.
4. Check schema-marked translatable fields
What can go wrong. A custom extension displays English text but its fields do not appear in Grunt translation exports.
Practical response. Inspect the plugin’s schema for translatable declarations and compare the exported segment set with all learner-facing strings. Treat any missing component as a coverage defect.
Prove it works. Add a test string in the custom component and confirm that the project’s supported export workflow includes it before commissioning a full translation. A target-language learner interacts with a complete system: a page title, a component, a question, feedback, media and eventually a completion record. Test the sequence, especially the moments where a person must act. Isolated proofreading misses how those elements depend on one another.
5. Protect plugin dependencies
What can go wrong. An imported language version contains values for an interaction that is missing from the target project, resulting in a blank or broken activity.
Practical response. Remember that importing translatable content does not install the plugins referenced by course data. Maintain a locked dependency list and compatible plugin versions.
Prove it works. Open the localized course with all representative interactions, including custom ones. A correct CSV import cannot compensate for a missing runtime component. Consider whether the problem is linguistic, structural, visual or operational. A wrong answer term needs translation review, a missing plugin needs dependency work, a reversed arrow needs design judgment and an LMS reporting failure needs deployment diagnosis. Fixing the right layer prevents random editing that creates new faults.
6. Export text without mistaking it for a complete course
What can go wrong. The organization sends languagefiles to a vendor and later expects the returned files to contain media, styles and all executable components.
Practical response. Treat the export as a transfer of declared translatable text. Plan separate handling for themes, assets, accessibility and runtime behavior.
Prove it works. Compare the contents of an exported translation package with the source project’s full resource inventory so nothing important is implicitly assumed to be included. Accuracy need not mean literal sameness. Regional examples may be adapted to be intelligible, while scoring and essential learning outcomes should remain equivalent. Decide which elements must remain identical, which may vary and who approves the difference. Without that boundary, a translation can turn into an undocumented change of curriculum.
7. Use the documented Grunt export command
What can go wrong. A team invents its own spreadsheet by copying visible strings, losing stable identifiers and context needed for reimport.
Practical response. For a compatible Framework project, use a supported export such as `grunt translate:export –format=csv` and preserve the produced files and their structure.
Prove it works. Test the export on a small course and inspect files such as `articles.csv`, `blocks.csv`, `components.csv`, `contentObjects.csv`, `course.csv` and the manifest information. Invest review time where errors have consequences. A stylistic blemish in a welcome paragraph is not equivalent to a reversed negative, incorrect threshold or inaccessible action. Prioritize meaning-bearing steps, graded decisions, alternate branches and anything a learner could use to make a consequential real-world choice.
8. Choose CSV, JSON or raw exchange carefully
What can go wrong. Translators use spreadsheet tools that rewrite delimiters or quoting, while developers assume all supported export modes offer identical editing experiences.
Practical response. Select a documented format that the translation team can handle without corrupting identifiers. Record any delimiter choice and ensure the importer uses matching settings.
Prove it works. Round-trip text containing commas, quotations, a line break and non-Latin characters. Check that values return to the intended field exactly. An important principle follows from this case: tool success and learner success are different forms of evidence. A command can complete and a page can render even when an instruction is ambiguous. Ask what the learner must understand and what observable behavior would demonstrate that understanding, then choose a test that actually measures it.
9. Preserve UTF-8 characters
What can go wrong. A translated language contains accents and non-Latin scripts, but the file is saved in a legacy encoding and the course displays replacement characters.
Practical response. Specify UTF-8 explicitly in the editing workflow and test the saved file, not merely the text shown in the spreadsheet editor.
Prove it works. Include strings with diacritics, right-to-left letters and punctuation in the pilot. Build the course and inspect the output in a real browser. Keep source authority visible. Translators can make language clear, while developers preserve runtime structure and subject experts approve factual or safety-critical changes. When these responsibilities blur, a well-intentioned technical repair may unintentionally rewrite the lesson. A short decision record protects both meaning and engineering integrity.
10. Keep record identifiers untouched
What can go wrong. An enthusiastic translator localizes `_id`, `_type` or field keys, destroying the relationship between components and their content.
Practical response. Explain the difference between a machine identifier and a visible label. Translate only the fields designated for human language, preserving keys, IDs and structural separators.
Prove it works. Validate JSON and compare identifier sets before and after translation. A meaningful title can change; the ID that connects the element should not. Do not treat translation as a one-off migration. A course will receive new knowledge, revised examples, updated plugins and changing media. The team that records why a value belongs in a certain file makes future changes safer; the team that merely gets one build to pass leaves fragile work for the next maintainer.
11. Distinguish text translation from JSON syntax
What can go wrong. A reviewer adds typographic quotation marks to JSON delimiters or leaves a stray trailing comma while editing the source directly.
Practical response. Use translation import methods when available and protect JSON syntax with validators. If direct JSON edits are required, distinguish values from control characters.
Prove it works. Run a parser and a course build, then view the affected page. Syntactic validity is necessary, but meaning and interaction tests must still follow. A target-language learner interacts with a complete system: a page title, a component, a question, feedback, media and eventually a completion record. Test the sequence, especially the moments where a person must act. Isolated proofreading misses how those elements depend on one another.
12. Use target folders that match language codes
What can go wrong. The course stores Spanish content in a folder named ‘Spanish-new’, but the language selector expects a standardized language-code path.
Practical response. Follow the documented convention of language-named folders, such as `en` or `de`, and coordinate exact codes between configuration, build options and picker entries.
Prove it works. Choose the language in the published course and inspect that the expected folder loads rather than falling back to an unrelated default. Consider whether the problem is linguistic, structural, visual or operational. A wrong answer term needs translation review, a missing plugin needs dependency work, a reversed arrow needs design judgment and an LMS reporting failure needs deployment diagnosis. Fixing the right layer prevents random editing that creates new faults.
13. Import with explicit target-language parameters
What can go wrong. An import command uses the wrong target code, updating the unintended locale or duplicating a folder.
Practical response. Check the `–targetLang` option, expected master and chosen format before running the documented `grunt translate:import` task. Treat `–replace` as consequential.
Prove it works. Run the import first on a copy and compare folder contents. A correct command must produce the intended language directory without damaging accepted existing content. Accuracy need not mean literal sameness. Regional examples may be adapted to be intelligible, while scoring and essential learning outcomes should remain equivalent. Decide which elements must remain identical, which may vary and who approves the difference. Without that boundary, a translation can turn into an undocumented change of curriculum.
14. Use `–replace` only with a recovery plan
What can go wrong. A project already contains expert-edited German text, and a replacement import destroys those changes.
Practical response. Backup the approved target-language folder and review changes before using replacement options. Prefer controlled merging where the supported workflow allows it.
Prove it works. Compare the imported edition with a list of protected terms, high-risk warnings and media paths. A technically successful replace may still represent editorial regression. Invest review time where errors have consequences. A stylistic blemish in a welcome paragraph is not equivalent to a reversed negative, incorrect threshold or inaccessible action. Prioritize meaning-bearing steps, graded decisions, alternate branches and anything a learner could use to make a consequential real-world choice.
15. Relink assets after importing language data
What can go wrong. An imported target course opens with broken images because text import did not copy assets or rewrite paths.
Practical response. Review each asset referenced by the localized JSON. Keep common visuals shared where appropriate and copy localized assets explicitly when language-specific differences are required.
Prove it works. Follow image and media URLs in the built output. Verify that they resolve on the deployed server, not only in the development environment. An important principle follows from this case: tool success and learner success are different forms of evidence. A command can complete and a page can render even when an instruction is ambiguous. Ask what the learner must understand and what observable behavior would demonstrate that understanding, then choose a test that actually measures it.
16. Translate informative image content
What can go wrong. A risk diagram contains English instructions, but the exported CSV includes only the surrounding caption.
Practical response. Inventory words embedded in images and create accessible target-language versions or descriptions. Coordinate visual replacements with the correct file paths.
Prove it works. Ask a target-language learner to interpret the diagram without source-language assistance. The core decision should remain understandable. Keep source authority visible. Translators can make language clear, while developers preserve runtime structure and subject experts approve factual or safety-critical changes. When these responsibilities blur, a well-intentioned technical repair may unintentionally rewrite the lesson. A short decision record protects both meaning and engineering integrity.
17. Review course-wide ARIA labels
What can go wrong. The page body is translated but assistive technology announces English navigation labels or vague controls.
Practical response. Include accessible names and relevant global ARIA text in the translation inventory. Confirm that the project’s schema and export settings cover them.
Prove it works. Use a screen reader configured for the target language and navigate the course without sight. Observe whether controls and feedback are meaningfully announced. Do not treat translation as a one-off migration. A course will receive new knowledge, revised examples, updated plugins and changing media. The team that records why a value belongs in a certain file makes future changes safer; the team that merely gets one build to pass leaves fragile work for the next maintainer.
18. Handle right-to-left language layout
What can go wrong. An Arabic course is readable in paragraphs but its menu alignment, icon sequence or mixed-script numbers lead learners in the wrong direction.
Practical response. Test the selected theme and components for right-to-left behavior. Use language-aware styling thoughtfully and avoid mirroring physical-world diagrams automatically.
Prove it works. Review on different screen widths with a fluent user. Ask which step comes next and whether numerals, product codes and arrows retain their intended meaning. A target-language learner interacts with a complete system: a page title, a component, a question, feedback, media and eventually a completion record. Test the sequence, especially the moments where a person must act. Isolated proofreading misses how those elements depend on one another.
19. Use HTML language attributes meaningfully
What can go wrong. A page has correct translated text but the document reports the wrong language, confusing pronunciation and assistive technologies.
Practical response. Ensure the target course sets an appropriate document language. Adapt’s localization documentation discusses `lang` and language-aware CSS rules; use them in context.
Prove it works. Inspect rendered HTML and test spoken output for a sentence, a number and an English product name embedded in the target script. Consider whether the problem is linguistic, structural, visual or operational. A wrong answer term needs translation review, a missing plugin needs dependency work, a reversed arrow needs design judgment and an LMS reporting failure needs deployment diagnosis. Fixing the right layer prevents random editing that creates new faults.
20. Localize the Language Picker settings
What can go wrong. The learner selects a language that lacks complete content, and fallback text creates a misleading impression of a finished edition.
Practical response. Install and configure the appropriate Language Picker extension for the languages actually present. Remember that the picker selects content; it does not create translations.
Prove it works. Test every listed choice after a clean launch. Each must load a complete, coherent target edition with working navigation and assessment. Accuracy need not mean literal sameness. Regional examples may be adapted to be intelligible, while scoring and essential learning outcomes should remain equivalent. Decide which elements must remain identical, which may vary and who approves the difference. Without that boundary, a translation can turn into an undocumented change of curriculum.
21. Validate default-language behavior
What can go wrong. The project defaults to English even though the audience expects a different opening language. A picker change later may affect progress unexpectedly.
Practical response. Set the documented default-language value intentionally and test any language-switching implications for bookmarking or LMS state in the actual configuration.
Prove it works. Launch with a new and a returning learner account, choose another language and observe whether progress and completion remain clear. Invest review time where errors have consequences. A stylistic blemish in a welcome paragraph is not equivalent to a reversed negative, incorrect threshold or inaccessible action. Prioritize meaning-bearing steps, graded decisions, alternate branches and anything a learner could use to make a consequential real-world choice.
22. Build selected locales deliberately
What can go wrong. A production build includes incomplete experimental language folders because the operator assumes the build will exclude drafts automatically.
Practical response. Use a supported language selection in the build process where available, such as `grunt build –languages=”fr,de”` in the documented environment. Only include tested locale folders.
Prove it works. Inspect the output package to ensure that every exposed language has its required resources. A folder’s presence is not proof of approval. An important principle follows from this case: tool success and learner success are different forms of evidence. A command can complete and a page can render even when an instruction is ambiguous. Ask what the learner must understand and what observable behavior would demonstrate that understanding, then choose a test that actually measures it.
23. Keep translation and assessment logic separate
What can go wrong. A developer edits scoring code to accommodate translated labels and accidentally changes which choice counts as correct.
Practical response. Translate learner-facing labels while keeping assessment logic and answer identity stable unless a subject-owner-approved change is necessary.
Prove it works. Use the same learner decisions in source and target editions and compare the resulting feedback and scores. The competence measured should remain equivalent. Keep source authority visible. Translators can make language clear, while developers preserve runtime structure and subject experts approve factual or safety-critical changes. When these responsibilities blur, a well-intentioned technical repair may unintentionally rewrite the lesson. A short decision record protects both meaning and engineering integrity.
24. Review feedback branches
What can go wrong. An incorrect response displays a source-language hint that lives in a different JSON field from the question stem.
Practical response. Test every significant feedback branch, including retries and end-of-course notices. Inventory conditional text rather than only strings shown on the first page.
Prove it works. Have a target-language learner make a deliberate mistake, read the feedback and correct the action without external explanation. Do not treat translation as a one-off migration. A course will receive new knowledge, revised examples, updated plugins and changing media. The team that records why a value belongs in a certain file makes future changes safer; the team that merely gets one build to pass leaves fragile work for the next maintainer.
25. Check the interaction plugins under translation
What can go wrong. A multiple-choice component works, but a custom drag-and-drop plugin uses hard-coded English validation text.
Practical response. Review localization support for each installed plugin and its translatable schema fields. Where custom code hardcodes strings, update the component through the supported development workflow.
Prove it works. Test at least one complete success and failure path per interaction type. Treat unseen error messages as learner-facing content that must be reviewed. A target-language learner interacts with a complete system: a page title, a component, a question, feedback, media and eventually a completion record. Test the sequence, especially the moments where a person must act. Isolated proofreading misses how those elements depend on one another.
26. Maintain source and target version relationships
What can go wrong. A revision changes component identifiers and structure, while older translations are reimported without accounting for new content.
Practical response. Track the master revision, dependency lock and target-language exports. Reconcile additions, deletions and moved elements rather than blindly applying an obsolete translation package.
Prove it works. Compare content model IDs and review high-impact changed segments. Run a targeted regression test after every structural update. Consider whether the problem is linguistic, structural, visual or operational. A wrong answer term needs translation review, a missing plugin needs dependency work, a reversed arrow needs design judgment and an LMS reporting failure needs deployment diagnosis. Fixing the right layer prevents random editing that creates new faults.
27. Test a source-to-target build pipeline
What can go wrong. The translated JSON validates, but the final web server serves a cached previous edition or a broken language-specific asset.
Practical response. Build, deploy to staging and inspect the actual served course. Verify network resources and learner navigation in the environment where the package will be used.
Prove it works. Record build source, target locales and visible revision. A local screenshot cannot prove that the delivered release uses the intended files. Accuracy need not mean literal sameness. Regional examples may be adapted to be intelligible, while scoring and essential learning outcomes should remain equivalent. Decide which elements must remain identical, which may vary and who approves the difference. Without that boundary, a translation can turn into an undocumented change of curriculum.
28. Check SCORM or web delivery behavior
What can go wrong. A course works as a standalone HTML5 page but loses bookmarking or completion in the LMS.
Practical response. Distinguish content localization from deployment integration. Test launch, progress, score and completion using the selected delivery format and plugins.
Prove it works. Run a fresh learner and a returning learner through one important task. Check that language selection does not silently change assessment evidence. Invest review time where errors have consequences. A stylistic blemish in a welcome paragraph is not equivalent to a reversed negative, incorrect threshold or inaccessible action. Prioritize meaning-bearing steps, graded decisions, alternate branches and anything a learner could use to make a consequential real-world choice.
29. Document language-specific style decisions
What can go wrong. One target language uses translated technical terms while another retains product labels. Without notes, future maintainers treat the differences as errors.
Practical response. Create a concise glossary of concept definitions, source terms, approved target equivalents, nontranslatable labels and acceptable regional variants.
Prove it works. Review a set of recurring terms across course-wide strings, page instructions, feedback and support materials. The learner should be able to find the same concept reliably. An important principle follows from this case: tool success and learner success are different forms of evidence. A command can complete and a page can render even when an instruction is ambiguous. Ask what the learner must understand and what observable behavior would demonstrate that understanding, then choose a test that actually measures it.
30. Prepare for future language updates
What can go wrong. The course is multilingual today but no one knows how to update one changed paragraph without replacing approved terminology or localized media.
Practical response. Preserve source revision, export files, target folder mapping, custom asset list, plugin dependencies, tested commands and review decisions. Plan selective changes rather than wholesale regeneration.
Prove it works. Rehearse a small revision involving one instruction, one interaction label and one localized image. The next editor should know exactly what to change and verify. Keep source authority visible. Translators can make language clear, while developers preserve runtime structure and subject experts approve factual or safety-critical changes. When these responsibilities blur, a well-intentioned technical repair may unintentionally rewrite the lesson. A short decision record protects both meaning and engineering integrity.
A four-week plan for an Adapt multilingual course
Week 1 — Inventory sources, plugins and learner decisions
Confirm the supported Adapt Framework revision, build environment and complete plugin list. Locate the master course under `src/course`, distinguish configuration from language data and identify every learner-facing string. Read the lesson as a student, including alternate responses, inaccessible paths and completion states. Record which fields are declared translatable and inspect any custom plugin that might conceal additional text.
Choose actual supported locales and clarify reviewer ownership. Write down source-language learning outcomes and high-risk rules. Build a small proof-of-concept lesson with a standard component, a custom interaction, an informative image and a feedback message. A representative pilot reveals missing schema declarations before a translator receives hundreds of files.
Week 2 — Export, translate and import carefully
Use a supported export format and preserve stable identifiers, valid quoting and UTF-8. Provide translators with context for ambiguous short labels, key glossary definitions and screen references. Keep a source revision while translation proceeds. Check every structured file rather than assuming that spreadsheet cells contain only prose. Where direct JSON editing is necessary, validate syntax and keep technical property names unchanged.
Import target data to correctly named folders, checking target language and replacement options carefully. Do not confuse the text import with installing plugins or copying images. Reconcile translated media, alternative descriptions and region-specific resources manually where needed. Build the target edition and inspect the actual rendered interactions.
Week 3 — Verify meaning, accessibility and technical behavior
Ask fluent target-language reviewers to perform an unprompted learner task. Include a correct and incorrect assessment response, a branch, an external resource, a video and an accessible control. Review readable language, substantive feedback and keyboard or screen-reader behavior. Check right-to-left layouts and mixed-script values when relevant, including the effects of theme CSS.
Validate build output, language selection and the destination deployment. Test a fresh learner and a returning learner, observing bookmarking, language changes, scores and completion. Document the failures by cause—translation, content schema, plugin, asset path or LMS—so the appropriate owner repairs them.
Week 4 — Release a maintainable multilingual edition
Approve each target language based on demonstrable instructional equivalence, technical stability and accessible delivery. Include only completed target folders in production builds. Preserve the source revision, generated exchange files, approved glossary, localized assets, dependency information and test evidence. Write a release note a new maintainer can understand without the original team’s private explanations.
Plan the next revision before considering this one finished. Identify how new fields will enter the translation export, how old target content will be protected during replacement and how testers will detect broken assets or changed questions. An open-source framework gives flexibility; disciplined maintenance turns that flexibility into dependable education.
Frequently asked questions
What is the main difference between translating an Adapt course and exporting a complete course?
Adapt’s translation export transfers declared translatable text fields; it is not the same as packaging every runtime file, plugin, asset and stylesheet. A translated course also needs correct language folders, references, components and compiled output. Treat text transfer as one stage of localization, not a whole-course migration.
Which Adapt files contain course-wide language?
The documented structure places language-specific content under folders such as `src/course/en`, with `course.json` containing course-wide strings. `config.json` is a separate configuration file. Additional pages, articles, blocks, components and plugins carry other text that requires inventory and review.
How does the framework decide which fields are exportable?
The Course Localisation documentation describes fields marked as translatable in the plugin’s `properties.schema`. Custom plugins without the expected schema declarations may have important strings omitted from the export. Audit plugins and compare the exchange files with actual rendered learner text.
How do Grunt translation commands work?
The Framework documentation describes tasks such as `grunt translate:export –format=csv` and `grunt translate:import –targetLang=de –replace`. Exact command availability depends on the installed project and version. Use a copied pilot, preserve file formats and identifiers, and verify the resulting course rather than assuming a successful command proves educational equivalence.
Does the Language Picker generate translations?
No. The Language Picker provides a choice among existing localized course folders. It does not create their content or assure accuracy. Configure it only for actual approved languages, test the fallback/default behavior and check whether switching languages changes progress or tracking in your environment.
Why might translated images be missing?
The documented text import does not automatically copy assets or update every path. Localized diagrams, videos and other media may need explicit copying, relinking and review. Confirm that paths work in a deployed build, not only on the development machine.
What should translators never modify in JSON or CSV?
Do not translate structural keys, stable IDs, machine values, file boundaries or protected placeholders. In CSV, preserve delimiters, quotes and UTF-8 encoding; in JSON, keep syntax valid. Translate the intended human-facing content and test it in the actual interaction.
How should right-to-left editions be tested?
Verify the document language, theme behavior, writing direction, mixed-script labels and visual sequence with a fluent reader. CSS and language settings help but do not decide whether an arrow should be mirrored. Test mobile layouts and keyboard or screen-reader navigation as well as ordinary visible prose.
Does passing a JSON validator guarantee a good translation?
No. Validation proves a structural property, not instructional correctness. A valid course can still present a misleading rule, ambiguous assessment, inaccessible control or old subtitle. Use semantic review, learner tasks and deployment checks after syntax and build validation.
How should an Adapt localization team prepare for future updates?
Keep source revisions, plugin dependencies, language folders, exchange files, asset mappings, approved terminology and a record of high-impact review decisions. Test a small update through the complete export/import/build process. Maintainability is a quality criterion because learning content changes after publication.
Official documentation and connected translation guides
See the official Adapt Framework Course Localisation documentation, Creating Your First Course guide, course.json documentation and Grunt task reference. To compare commercial authoring workflows, read Translate Like a Pro 4290 — Gomo multilingual courses. For the broader architecture, read Master Art of Translation — Education and Learning Systems. Confirm toolchain versions and extension behavior in the environment you actually run.
Translate like a professional by protecting both sides of the work: the language that teaches and the structure that delivers it. A correct CSV import, valid JSON and successful build are necessary technical achievements; a clear learner decision, accessible explanation and verified completion show that the course is genuinely ready to teach.