How can you translate an H5P interactive learning activity without breaking its questions, embedded media, editor controls or reusable library structure? An H5P package is more than a set of sentences. It combines a structured package description, learning content, dependencies and reusable content-type libraries. Human-facing language appears in different places depending on whether the text belongs to a specific learner activity, the authoring editor or a content-type library. A professional localization therefore begins by locating the right layer before anyone changes a word.
This guide explains how to localize H5P .h5p files, h5p.json, content/content.json, semantics.json, library.json, library language folders, embedded interactive questions, feedback strings, multimedia descriptions, alt text, accessibility messages and multilingual classroom delivery. It is written for educators, digital course designers, platform operators, content-type developers, translators and training providers who want interactive exercises to work across languages. It also addresses packaging, library version compatibility, answer-key protection, H5P’s use of xAPI events and functional testing for authoring and learner experiences.
The official H5P documentation describes the .h5p file as a structured zip package. Its package definition names a main library, language and dependencies; the content data is typically stored in content.json; and reusable libraries describe their editing fields through semantics.json. Library translation files are a different matter from translating the lesson instances created with those libraries. This article treats those boundaries carefully, distinguishing what the learner reads from what the editor needs and what the system executes. Examples are fictional and are not guarantees that every H5P platform integration supports identical import, reporting or language-selection behavior.
How to use the guide
Read the architecture and decide which layer owns each sentence. Then work through thirty realistic content and library decisions, the deeper review questions, a four-week implementation plan and the FAQ. The recurring test is simple: can the author maintain the activity, can the learner complete it, and can the system still interpret it correctly?
The H5P localization architecture
Understand the package as a small application
An H5P interaction depends on content, a content-type library and a platform capable of playing it. Translating the activity text does not update the library’s editing controls; translating a library language file does not automatically rewrite every existing authored question. The platform integration also contributes its own navigation and authentication.
Before editing, determine whether the requested localization concerns a particular exercise, the content type’s default interface, the editor experience or the hosting platform. Each has a different owner and test plan.
What h5p.json describes
The package definition contains metadata such as a human-readable title, a mainLibrary reference, a language value, embed types and dependencies. Some entries are language-bearing, whereas machine names and library versions are structural. The official H5P package definition documents which fields are mandatory and how they are interpreted.
Translate the package title where appropriate and use a supported language code. Keep machine dependency names and versions exact. A pleasant localized title cannot repair a missing dependency.
What content/content.json does
Content.json holds the parameters used by the main interactive library. Those parameters can include learner-facing instructions, question text, labels, feedback, resource references and nested activities. The actual shape depends on the chosen content type’s semantics, so two H5P activities may store similar visible text in different locations.
Do not use a blind search-and-replace across JSON. Inspect the content type and identify fields whose values are text, structural choices, answer markers or resource paths.
Why library.json and semantics.json are different
The library definition records the reusable component’s identity, version and dependencies. Its semantics definition describes fields the editor presents and accepts. A field can have a machine name, a type and a visible label, and those are not interchangeable. The content itself will later be validated using the defined structure.
Translate intended labels and descriptions through supported translation methods. Preserve field names, field types, dependency identity and any constraints that code relies on.
Library language files are not exercise data
H5P allows language files for library semantics and editor strings. This can make the content-creation interface usable for authors of different languages. The existing exercise authored by a teacher still has its own specific instructions and answers in content data.
Plan two review rounds: a content-authoring round for the localized editor and a learner round for an actual activity. Passing one does not prove the other.
The role of language folders
H5P’s library translation guidance describes files placed in a library language folder with an appropriate language-code filename. The translation objects reflect the corresponding semantics structure, rather than constituting a free-form dictionary. Editor widgets may have their own language strings.
Preserve the expected JSON object shape and use appropriate language tags or codes for the supported implementation. Inspect runtime fallback instead of guessing how the platform chooses a language file.
A content-type library can have nested dependencies
An interactive activity can include a library within another library, such as a question set containing individual question types. The outer activity may be translated correctly while a nested module retains English feedback or missing prompts.
Inventory every nested component and version. Test the actual assembled activity rather than checking only the top-level content.json.
Why answer keys are not just text
Some interactions encode correct answers through specific markers, options, ordering, indices or structured response rules. Translating or reordering visible options can inadvertently alter the correct selection or make the original clue meaningless.
Review question, accepted answers, distractors, feedback and scoring as one educational unit. Conduct a blind attempt with native-language reviewers, not merely a grammatical comparison.
Media and accessibility carry learning meaning
Images can include answer-bearing labels. Audio may present clues absent from captions. Video questions can appear at particular times. Alternative text, transcripts and accessible button names are part of what learners receive, not optional decoration.
Build a media inventory with translated narration, captions, transcript, alt text and display labels. Test learning without relying on hearing or precise mouse control.
H5P may communicate xAPI events
H5P libraries can make xAPI statements available to host integrations. Whether and how those events become LMS records depends on the surrounding platform. The existence of event capability does not by itself guarantee completion tracking or transfer to an LRS.
Test the intended reporting path. Keep stable activity identifiers and statement semantics where required, and never infer an award merely from a translated on-screen success message.
Library versions and package portability
An H5P package can depend on particular content-type library versions. A package that works in one site may need an update or compatible library on another. Repacking text files is not the same as verifying dependencies and migration behavior.
Record source and target library versions, import permissions and supported content types. Test a localized package in a second clean environment before calling it portable.
What professional localization changes
The goal is not to convert everything that looks like English into another language. It is to make learner tasks, instructions and editor controls comprehensible while preserving correct answers, runtime code, metadata contracts, media paths and accessibility. That requires language and technical review working together.
A release is ready only when authors can edit it, learners can complete it, and the hosting platform continues to produce the intended result.
Thirty H5P localization and portability decisions
Every fictional situation below separates the visible language from underlying content structure, learner outcome and cross-platform behavior. A good correction should be readable to people and testable by someone who did not perform the translation.
1. The activity title changes but the mainLibrary also changes
A course editor translates a package title and then changes the mainLibrary machine name because it looks like an untranslated English phrase. The uploaded activity no longer finds the intended content type.
Package title and library machine name have separate functions. One is human-readable context; the other is a dependency reference. Replacing the latter is a structural change.
Translate the display title only. Preserve the mainLibrary value and confirm the referenced library version is present.
A useful test: Reimport the .h5p file and open the activity on a staging site with a clean library inventory.
2. An author edits JSON without preserving its structure
A translation team copies content.json into a word processor, changes labels and reexports it as text with extra punctuation. The resulting file cannot be parsed as JSON.
Structured data requires valid quotes, commas, braces, encoding and value types. Human language review cannot substitute for structural validation.
Use tools that preserve JSON syntax and separate values from keys. Keep an unmodified baseline and compare intended fields only.
A useful test: Parse the file, import it and open all edited question components. A valid parse is the beginning, not the end, of QA.
3. A field name is translated as though it were a label
A semantics.json field uses name for its internal key and label for a friendly description. A well-meaning reviewer translates both and the editor no longer matches saved parameters.
Machine names connect configuration and code. Labels and descriptions explain fields to human authors. Their visual proximity in the JSON does not make them equivalent.
Preserve the name and type fields. Translate the approved semantics strings in the library language file instead of changing the schema.
A useful test: Create a new exercise with the localized editor and reopen a previous one. Both must retain field values correctly.
4. Library language files are placed in the wrong directory
A translator prepares a correct language JSON file but uploads it beside content.json rather than inside the relevant library’s language folder.
The loader expects a defined package structure. A correct sentence in an undiscoverable file will never appear to authors.
Follow the official library directory convention and supported language-code filename. Keep editor-widget translations in their proper component as well.
A useful test: Select the locale in the editor and verify that labels and placeholders are actually loaded.
5. An existing learner question remains English after editor translation
The authoring form now shows translated controls, yet an old lesson still asks a question in English. The team assumes the language package was ignored.
The editor’s interface translations and an activity’s authored content are separate. Changing one does not automatically rewrite the other.
Translate the actual question text in the activity content and review the library UI strings as a different deliverable.
A useful test: Open both the authoring form and the learner view for the same locale. Record what belongs to each.
6. An answer marker is lost in a fill-in-the-blank exercise
A translator rewrites a sentence naturally but removes special punctuation used by the exercise to identify a blank and accepted responses.
A text field can have authoring syntax that carries grading meaning. The words are readable, yet the component no longer knows which phrase constitutes the answer.
Read the content type’s authoring rules before changing the sentence. Rebuild the localized blank and accepted variants according to supported syntax.
A useful test: Answer correctly and incorrectly in the target language. Check the feedback and actual score.
7. A distractor becomes defensibly correct
A multiple-choice question tests the safest action in an emergency. One translated wrong option is phrased as a reasonable alternative because the nuance changed.
The learner now faces more than one plausible answer, but the original key has not changed. A syntactically valid package can still be pedagogically invalid.
Have a subject specialist review every choice and its explanation together. Adapt the scenario only if the intended competency remains unambiguous.
A useful test: Ask local-language pilot learners to justify their answers without showing the key. Investigate contested choices.
8. An answer’s case and accent handling is misunderstood
A short-answer activity accepts one specific string. The translator introduces accents and local spellings, while the component’s matching rules remain configured for the source language.
Whether accent, case, spacing and spelling variants are accepted depends on the question type and its configuration. Translation alone cannot promise equivalence.
Document supported acceptable forms and configure them within the content type’s semantics. Avoid claiming fuzzy matching unless it is actually implemented.
A useful test: Test expected alternatives, common errors and near misses. Confirm that grading is consistent with the learning objective.
9. A timeline graphic still contains source-language labels
The main text is translated, but an image embedded in the activity has English labels that carry the answer. Learners who cannot read them lose essential information.
Text inside graphics is part of the learning material even if it is not exposed as a normal JSON string.
Inventory graphics, animations and diagrams. Provide appropriately localized assets and descriptions while retaining copyright and attribution information.
A useful test: Attempt the task using only the translated version; ask reviewers to identify any inaccessible or untranslated clue.
10. An audio instruction contradicts its caption
A localized narration says to select the second option, but a legacy caption says the third. The activity records a wrong answer for users who rely on captions.
A mismatch between modalities is a learning equity problem, not a minor typographical error. Some learners receive a different instruction.
Synchronize narration, captions, transcript and any onscreen text against one approved instruction set.
A useful test: Test the task with audio muted and with captions enabled. Verify that both paths yield the same intended action.
11. A library update removes a customized label
An author patches a language string directly into a distributed library file. The next library upgrade replaces the file and restores the source-language text.
Ad hoc edits may not survive dependency updates. A package localization needs a maintainable source of truth and documented deployment procedure.
Keep localization resources within supported mechanisms and version control. Reapply or merge them deliberately when libraries change.
A useful test: Upgrade a staging copy and compare the editor and learner interface before approving the new library version.
12. A locale falls back without telling the author
An editor selects a less common language, but a missing library translation silently falls back to English. The published course is partly translated and the team does not notice.
Fallback is useful for resilience, yet it can conceal missing work in a multilingual release. Users experience a mixed-language authoring interface.
Keep a coverage list of libraries and supported locales. Review which messages use fallback and prioritize important learner-facing strings.
A useful test: Walk through the editor and activity with a clean language profile, logging untranslated placeholders and messages.
13. One content type has several nested activity libraries
A question set mixes multiple-choice, drag-and-drop and a summary task. Only the outer title is translated; child feedback still appears in English.
Nested content libraries carry their own authoring data, UI strings and answer semantics. A package-level title is not a translation of all dependencies.
Expand and review every nested library and its reusable messages. Track which dependency owns each visible string.
A useful test: Finish the full activity, including every question type and its feedback, in the target locale.
14. A drag-and-drop hotspot moves after text expansion
Longer localized labels change layout around a drag-and-drop exercise. The visible drop targets no longer align with their intended shapes or words.
Localization can change geometry even when the data remains structurally valid. A learner may misplace an answer because the interface shifted, not because of misunderstanding.
Test responsive layouts and adjust permitted presentation settings without changing scoring relationships. Avoid solving layout problems by shortening essential instructions until ambiguous.
A useful test: Check desktop, tablet and mobile sizes, including zoom and long-word languages.
15. A video question appears at the wrong conceptual moment
Translated narration takes longer than the source audio, while a timed interactive question still appears at the old position. It interrupts before the necessary explanation.
Interactive timing is an instructional parameter. A faithful translation can require a carefully approved timing adaptation for equivalent learner understanding.
Review interaction timestamps against the final localized media. Preserve the question’s purpose while verifying timing, pauses and playback behavior.
A useful test: Watch the video from start to finish and attempt every interaction without knowing the source timing.
16. A feedback template loses a variable
A result message contains a placeholder for achieved score or total. A translator removes the placeholder to improve the sentence, leaving the UI unable to show the relevant quantity.
Placeholders can carry essential data. Their exact syntax must often be preserved even if surrounding grammar needs reordering.
Mark variables as protected, verify supported formatting and adapt syntax only through documented localization facilities.
A useful test: Submit results with different scores. All messages should show accurate quantities and grammatical agreement.
17. An author assumes an H5P score is the official LMS grade
An H5P activity displays a score, but its hosting environment does not send that result into the institution’s gradebook. A translated certificate-style message claims the learner has earned course credit.
An activity’s local feedback, xAPI events and an LMS’s authoritative grade are distinct. Integrations determine what is recorded and recognized.
Write the message to reflect the verified outcome. Test reporting through the actual host instead of inferring it from the score screen.
A useful test: Inspect the gradebook or LRS after a controlled attempt; identify which component owns the result.
18. A copied package contains private learner examples
A teacher uses a real learner response in a demonstration activity and sends the .h5p package to a translation provider.
Learner details can spread through content files and screenshots. Translation does not authorize reuse of personal information.
Replace sensitive examples with fictional responses and strip private metadata before distribution. Apply organizational privacy rules to test data.
A useful test: Review extracted package contents and screenshots as part of the security check.
19. A link destination is translated into a broken address
An instructional hyperlink’s visible text is localized, but the editor also rewrites the URL’s path segments as words.
The target address is a routing resource, not a sentence. The page could fail even though the link label seems natural.
Translate meaningful link text while verifying the correct localized destination actually exists. Do not invent a destination by translating its slug.
A useful test: Click every link from the finished activity and verify the intended accessible resource opens.
20. A localized asset is not included in the exported file
The activity works on the authoring site because the translated image is hosted there, but the downloaded package omits it or references a private server.
Portability depends on bundled resources and resolvable references, not just what the original site can display.
Check whether media is embedded, linked or subject to platform restrictions. Include supported files in the package and document external dependencies.
A useful test: Import into an isolated site and inspect the page with the original host unavailable.
21. JSON strings contain unescaped quotation marks
A translator inserts a direct quotation inside a JSON value without escaping it. The package stops loading when parsed.
The problem is not the target language; it is the representation of literal quotation marks and control characters in structured data.
Use JSON-aware editing and serializer tools that escape values correctly. Keep smart punctuation only where it is legitimate content.
A useful test: Parse and validate the final JSON, then confirm the rendered quotation appears as intended.
22. Bidirectional text reverses an identifier visually
An Arabic or Hebrew activity includes Latin technical terms and a reference code. Visual direction changes their apparent order, prompting learners to copy the wrong code.
Mixed-direction text requires careful presentation. Exact identifiers must remain machine-correct even when surrounding prose is right-to-left.
Use supported directionality and isolation techniques in the host UI. Preserve identifier bytes and test copying as well as appearance.
A useful test: Ask reviewers to read and copy mixed-script values on several browsers and assistive technologies.
23. Default feedback phrases carry the wrong tone
An H5P library supplies generic messages such as ‘Check’, ‘Retry’ or ‘Show solution’. A literal translation has unintended harshness or describes the wrong action.
Short functional text needs context. ‘Check’ can mean inspect an object or submit answers for marking; those are different actions.
Translate the actual button behavior and use natural, encouraging language without changing scoring or access permissions.
A useful test: Ask a learner what they expect each button to do, then compare it with the result.
24. Library attribution disappears from a localized copy
The translator creates new media files and removes credit metadata while rebuilding the package. The activity still works but no longer acknowledges the original creator or license.
Attribution and reuse rights remain relevant across languages and formats. A translated package is not automatically free of its source obligations.
Preserve required creator, license and credit information, adding translated explanations without falsifying authorship.
A useful test: Inspect package metadata and the visible credit display against the approved source permissions.
25. A performance improvement strips accessibility text
A deployment pipeline removes seemingly unused labels and descriptions from the H5P data. Screen-reader users lose instructions while visual users see no obvious change.
Strings may be consumed by assistive technology or editor widgets even when they are not visible in the primary interface.
Treat accessibility fields as content dependencies. Validate with keyboard and screen-reader testing before minifying or cleaning assets.
A useful test: Complete core tasks without a pointer device and verify descriptive information remains available.
26. A translated timer changes assessment conditions
A quiz instructions panel converts a time allowance into another unit incorrectly. Learners believe they have longer than the exercise timer actually permits.
A quantity is both language and rule. Formatting or unit conversion must preserve the same duration if the assessment is meant to be equivalent.
Document the actual configured time and choose unambiguous units. Change the timer only through approved assessment adaptation, not as a side effect of translation.
A useful test: Run the quiz against a clock and compare the displayed limit with behavior in all locales.
27. The answer explanation introduces a new claim
A localizer improves a scientific explanation by adding an unsupported example. The learner begins to associate the correct answer with a fact that is not reliably true.
Educational nonfiction requires evidence and qualified scope. Translation review should not become accidental content invention.
Keep explanatory claims linked to the approved objective and sources; obtain subject-expert approval for substantive additions.
A useful test: Ask an independent reviewer to identify statements that go beyond the original evidence.
28. A small-screen language switch covers the submit button
A longer locale name expands the dropdown and overlays an H5P control. The exercise appears normal until the learner reaches the final step.
Responsive failures can create unequal completion opportunity. Layout must be tested under actual strings, scripts and zoom levels.
Use supported responsive design and accessible labeling. Avoid breaking library UI styles with localized custom CSS unless reviewed.
A useful test: Submit an activity at common screen widths, high zoom and keyboard navigation in each released locale.
29. A translator declares success because all visible words changed
An H5P export contains no obvious English strings, but its correct-answer logic, package metadata, library dependencies and report events have not been checked.
A word inventory is useful but insufficient. Functional equivalence requires a learner to experience the intended task and the host to record the right result.
Combine linguistic review with JSON validation, import testing, blind learner attempts, accessibility checks and supported reporting verification.
A useful test: Produce a release report that names the tested components and observed outcomes instead of a generic ‘translation complete’.
30. A content update breaks an older classroom copy
An H5P library and activity package are revised together, then imported into a site where some older classes use an earlier content-type version.
Library migrations may transform content data or alter behavior. A translation that succeeds on the newest site may be incompatible with an older deployment.
Version the package, document compatible library versions and keep backups. Test the target version and update path explicitly.
A useful test: Open and complete the activity on every supported deployment version before announcing portability.
Eight deeper principles for designing multilingual H5P
Separate the author and learner journeys
H5P is unusual because its authoring interface can be as linguistically complicated as the exercise itself. One person needs to understand field labels, defaults and instructional help; another needs to understand prompts, choices and results. A common translation plan that checks only the learner view can leave authors unable to maintain the localized resource.
Build a paired review for the same content type: one task asks a teacher to create and modify a question; the next asks a learner to complete it. Verify that both can do their work without reverting to the original language.
Treat content types as different contracts
An image hotspot, an interactive video and a fill-in-the-blanks question may all show a title and feedback, but their data shapes and assessment rules differ. A universal extraction rule is unlikely to know which strings are safe to move, which contain markup and which carry special answer syntax.
Maintain a per-library inventory of textual fields, allowed markup and answer semantics. Reuse translation only when functional context matches, not merely when source words look identical.
Preserve assessment fairness
Good educational localization does not mean giving every country an identical story. It means allowing learners to demonstrate the same intended knowledge under equivalent instructions and constraints. Local examples can improve comprehension, but changes in measurements, names or cultural assumptions may alter the reasoning needed to answer.
Review each assessment as a unit: learning outcome, prompt, media, correct answer, distractors, feedback and reportable result. Record the justification for any adaptation that changes content beyond ordinary wording.
Validate structure before language acceptance
A JSON parser proves that a file is syntactically readable; it does not prove its data corresponds to the library semantics or that a question can be answered. Conversely, a browser preview may load from a cached asset while the exported package is missing a dependency.
Use a sequence of tests: parse files, inspect declared dependencies, import into a clean environment, exercise every interaction and compare results. Each stage catches a different kind of defect.
Plan for maintenance rather than a one-off file
An H5P course may be revised by teachers, bundled into an LMS, copied between campuses and updated with new library versions. If translation history does not follow the file, later editors cannot tell whether a string came from a library, an activity or a platform.
Keep a maintained source record for each language, component and version, along with approved terminology, media permissions and tested package revisions. Avoid undocumented fixes that work only on one installation.
Know the limits of an event stream
An interactive component may emit xAPI statements, but a host platform may collect, transform or ignore them. A displayed answer score therefore need not be identical to a transcript grade or a credential decision. Publishing text that promises an award is a separate claim requiring actual evidence.
Trace one successful and one unsuccessful attempt through H5P, the integration layer and the official learner record. If the chain stops before the gradebook, state that limitation to learners and institutions.
Make accessibility measurable
Alt text, captions, keyboard navigation, contrast and readable status messages serve different users and should not be treated as optional polish. A translated activity may add words that increase reading load or cause a button to wrap. Layout and pacing are therefore instructional questions too.
Have target-language reviewers test screen reader, keyboard, small-screen, zoom and audio-off scenarios. Record whether the task can be understood and completed, rather than simply whether the interface renders.
Protect the meaning of failure
An error can mean the platform rejected the file, an image is missing, a learner gave an incorrect answer or an event could not be reported. Localizing all of these as ‘failed’ hides the next action and can produce unjustified alarm.
Write state-specific messages: retry a network request, contact an administrator, review an answer or wait for reporting. Verify each message by inducing its actual triggering condition.
A four-week learning and localization plan
Week 1 — Inventory the content and library landscape
List every .h5p package, mainLibrary, dependency, content type, editor widget, authored question, media file and supported locale. Compare the source activity with its reusable library UI. Define protected keys, field constraints, answer markers and expected results. Export a baseline, then import it into a safe test environment.
Week 2 — Localize authoring and learner material separately
Translate permitted package titles, content strings, feedback, accessible descriptions and authorized editor language resources. Preserve JSON keys, dependencies, version numbers and answer structure. Review source and target examples against educational objectives. Keep all changed files traceable to their approved origin.
Week 3 — Validate every interaction and accessible path
Parse the JSON, rebuild the package, test import and complete every nested question type. Try correct and incorrect responses, variables, retries, mobile screens and assistive access. Test captions and transcripts against final media. Check what results are actually reported in the hosting LMS or other system.
Week 4 — Release and maintain the multilingual package
Approve language, technical, subject-matter and accessibility results. Keep a rollback copy and compatibility record by H5P library version and platform. Train course authors to distinguish language-file updates from edits to individual activities. Review support reports and revise misleading messages without changing historical learner results.
Frequently asked questions
What is an .h5p file?
It is a structured archive that can hold H5P package metadata, content, media and reusable library dependencies. Its internal conventions matter when importing and sharing an activity.
Where is the learner’s text stored?
Often in content/content.json, according to the main library’s semantics; nested libraries and media may carry additional user-facing content.
What is semantics.json?
It describes the fields and constraints of an H5P content type. The editor can use it to build a form and validate the content data.
Can I translate JSON keys?
Not indiscriminately. Field keys and machine names often identify schema properties. Translate intended values and supported language resources.
Why is translating the H5P editor different?
Editor field labels and widget strings belong to library resources, whereas an existing authored activity has its own question text and media.
Does H5P automatically put grades into my LMS?
Not necessarily. H5P can expose xAPI events, but official reporting depends on the host integration and configuration.
Can I change answer choices when localizing?
Sometimes, but always check that the question still assesses the same objective and retains a defensible correct answer.
How should I test an interactive video?
Check translated captions and narration, timed questions, button labels, mobile behavior and reported results across a complete playback.
What makes a package portable?
Valid structure, resolvable assets, compatible library versions and successful import and playback in the target platform.
What is the difference between this guide and quick H5P QA?
This guide explains the complete package and library localization architecture; focused QA guides examine narrower interactions such as individual questions or timed video checks.
Authoritative H5P documentation and related reading
Use the official H5P package specification, h5p.json package definition, semantics definition, library translation guidance and technical overview. These documents explain package structure and library responsibilities. Check the actual content-type and platform versions you deploy; there is no universal guarantee that all installations behave identically.
Related eduKateSG guides: H5P question QA, H5P interactive video QA, xAPI event meaning and the Translate Like a Pro series index.