Translate libraries
Translating library semantics
Being able to translate your content is essential for reaching out to everyone. That is why translating content in H5P is made easy - all you need to do is include a language file in the language folder of your library. The different steps for creating and placing this language file is explained in the following three steps:
- Make a language file from your semantics.json file.
- Rename the new file with the correct language code, and place the file in the correct folder.
- Translate the strings in the file.
The H5P framework will take care of the rest!
Create translation
Creating the languages file from the semantics file can be done in two ways.
- Use the H5PCLI tool to create the language file for you.
- Create the language file manually from the library semantics.json file.
Using the H5PCLI tool
The H5PCLI is the H5P Command Line Interface, this tool is made with library developers in mind, trying to make their life easier. For a complete overview of the CL, and the mindset of becoming a faster and more efficient H5P developer you should check out the H5P CLI guide.
Once you have the H5P CLI you can translate the file by typing
h5p create-language-file h5p-summary nb
Since the CLI takes care of the language file naming convention and placement you can proceed straight to translating the content of your new file!
Create the language file from semantics.json
Making a language file that is ready to be translated from semantics.json is achieved by following three quick steps.
- Copy the semantics.json file from your library
- Remove all fields that do not need translation
- Encompass the content in a semantics object.
Copy the semantics.json file
The simplest step. Make a new file and copy the complete content of semantics.json to this file.
Remove all fields that do not need translation
A field definition in semantics.json looks like the following:
{ "label": "Textfield", "name": "textField", "type": "text", "widget": "textarea", "placeholder": "This is an answer: *answer*.", "description": "Marked words are added with two asterix (*) around the word." }
name, type and widget are not displayed to the end user, but needed only by the editor, so they should be left untouched.
Following is the complete list of fields that can and should be translated:
- Label
- Placeholder
- Description
- Default
All other fields should be removed from the new language file, which would result in our example looking like this:
{ "label": "Textfield", "placeholder": "This is an answer: *answer*.", "description": "Marked words are added with two asterix (*) around the word." }
Enclose the content in a semantics object
The H5P Editor looks for a "semantics" object in the language file, which must match the structure of your semantics.json file. This step is completed by simply adding an outer object with a field called semantics. This fields should contain the modified semantics.json file from last step.
Using Fill in the Blanks as an example, its prepared language file would look like this:
{ "semantics": [ { "label": "Task image", "description": "An optional image to display above the task." }, { "label": "Task description", "description": "A guide telling the user how to answer this task." }, { "label": "Text blocks", "entity": "text block", "field": { "label": "Line of text", "description": "Blanks are added with an asterix (*) in front and behind the correct word/phrase. Alternative answers are separated with a forward slash (/). You may add a textual tip, using a colon (:) in front of the tip. Example: H5P content may be edited using a *browser/web-browser:Something you use every day*." } }, { "label": "Feedback text", "description": "Feedback text, variables available: @score and @total. Example: 'You got @score of @total possible points'" }, { "label": "Text for \"Show solutions\" button" }, { "label": "Text for \"Retry\" button" }, { "label": "Text for \"Check\" button" }, { "label": "Text for \"Not filled out\" message" }, { "label": "Behavioural settings.", "description": "These options will let you control how the task behaves.", "fields": [ { "label": "Enable \"Retry\"" }, { "label": "Enable \"Show solutions\" button" }, { "label": "Automatically check answers after input" }, { "label": "Case sensitive", "description": "Makes sure the user input has to be exactly the same as the answer." }, { "label": "Require all fields to be answered before the solution can be viewed" }, { "label": "Put input fields on separate lines" } ] } ] }
For an advanced reference example, you can see the semantics.json of Image Hotspot Question and the corresponding Norwegian language file
Name and place of translation
Next up is giving the language file a proper name and placing it in the correct folder for the editor to find it.
The naming convention of languages we use is the two-character ISO-639-1 standard. A list containing language codes for this standard can be found at Wikipedia.
When you have found what language you wish to translate to you will simply rename the language.json file to <language-code>.json.
The file should then be placed in the language folder immediately within your library. If this folder does not exist it must be created.
Let the translation begin
This step is quite straightforward, but naturally the most time consuming. This is where you will be doing the actual translations.
When you have finished the translation you are done! The editor will take care of loading the correct language file as long as you have your language configured correctly on your server.
Translating editor widgets
Editor widgets are handled quite similarly to semantics.json translation. However, there are some key issues that the developer has to take care of in these cases.
Editor translates semantics
When using semantics from the main library in a widget they have to be processed inside the widget. The semantic chunks can be processed and used by using H5PEditor.processSemanticsChunk, in these cases the editor will take care of the translations from semantics, as long as you have translated the semantics in your library, as described for the semantics.json file.
Widget translates strings
When not using text strings from semantics.json as UI texts, the developer has to use the H5PEditor.t function, which is only available in the editor.
All UI texts should be translatable in an editor widget, so they have to be included in the H5PEditor.language object. This is done by creating a property on that object using the machine name of your library as the key. For the H5PEditor.ImageHotspotQuestion editor widget, adding the following to the bottom of the JS file will create the default English texts strings that can be translated:
// Default english translations H5PEditor.language['H5PEditor.ImageHotspotQuestion'] = { libraryStrings: { noImage: 'You have not selected an image.', done: 'Done', remove: 'Remove hotspot', rectangle: 'Create rectangle', circle: 'Create circle', guiDescription: 'Drag and drop the desired figure from the toolbar to create a new hotspot.' } };
Similarly to the library translations a "language" folder must be created within the editor library and the translation files must be named <language-code> .json, see section above. The content of the file will be the same JavaScript object appended to the H5PEditor.language array in the code above. Here is the content of the Norwegian language file for the example above:
{ "libraryStrings": { "noImage": "Du må velge et bilde før du kan plassere målfelt.", "done": "Ferdig", "remove": "Slett målfelt", "rectangle": "Lag rektangel", "circle": "Lag sirkel", "guiDescription": "Dra og slipp en figur for å lage et nytt hotspot. Dobbel-klikk en hotspot for å velge innstillinger. Dra en hotspot for å bevege den. Dra nede til høyre på hotspoten for å endre størrelsen." } }
To get a string with correct translation in your JavaScript code, invoke H5PEditor.t with the editor library's machine name and the key of the string like this:
H5PEditor.t('H5PEditor.ImageHotspotQuestion', 'noImage');
Comments
frankle1402
Sun, 09/18/2016 - 05:28
Permalink
Only Work for the first time?
I tried to make a json file in Chinese and upload .h5p file into a new 2.9+ moodle site, it works fine. And the editor will be in Chinese each time I try to add a new content.
But What if I would like to Modify the Translation of the Editor? I just can't do it anymore, not matter what .h5p file I uploaded, the editor stay the same with the first version of translation.
So, How could I Modify the Translation of the Editor?
thomasmars
Mon, 09/19/2016 - 10:04
Permalink
Hi,
I assume you mean translating the H5P Core editor, not just an editor widget. In order to translate the H5P Core you can follow the Translating guide for "Modules and plugin".
papi Jo
Sun, 12/11/2016 - 23:57
Permalink
Suggestions to improve the translation process
I have been looking at the H5P libraries which currently are not at all or incompletely translated into French. I have installed H5P CLI and executed the "
h5p create-language-file LIBRARY_NAME fr" command which works as expected.
I have also remarked that some language files in some libraries include both the original English strings and the translated strings, e.g. here's an extract from h5p-accordion, nb file (Norwegian):
"englishLabel": "Panels",
"label": "Paneler",
"englishEntity": "panel",
"entity": "panel",
"field": {
"englishLabel": "Content",
"label": "Innhold",
"englishEntity": "content",
"entity": "innhold",etc.
In my opinion this is much better for translators than starting from an all-English file such as the "prepared language file" that is output by the H5P CLI "
h5p create-language-file h5p-summary fr" command. It is indispensable that the original English strings be retained so that translators checking, completing, correcting language files can actually work from the original.
My suggestion if to revise the createLanguageFile(library, languageCode, results) function in h5p-cli.js so that it will not only "Remove untranslatable properties from semantics" but output the newly created lang file something like:
"englishLabel": "Panels",
"label": "",
"englishEntity": "panel",
"entity": "",
"field": {
"englishLabel": "Content",
"label": "",
"englishEntity": "content",
"entity": "",etc.
Does that sound feasible?
tim
Wed, 12/14/2016 - 09:27
Permalink
Discussion continued in the
Discussion continued in the following thread:
https://h5p.org/node/38157
papi Jo
Wed, 01/04/2017 - 16:38
Permalink
I would like to know how
I would like to know how those language files including "english" strings were produced. Was a customized version of H5P CLI "
h5p create-language-file ..." used for the purpose?
tim
Wed, 01/11/2017 - 10:01
Permalink
I think it may be the command
I think it may be the command 'add-english-texts' that does that.
tim
Wed, 01/11/2017 - 10:01
Permalink
I think it may be the command
I think it may be the command 'add-english-texts' that does that.
papi Jo
Wed, 01/11/2017 - 15:23
Permalink
Thanks for pointing to that
Thanks for pointing to that command, tim.
However, on my localhost test site, the command
create-language-file <library> <language-code> works fine but the command add-english-texts <language-code> <library> [<library>...] with
H5P.Dialogcards-1.4 for library name
returns an error: H5P.Dialogcards-1.4 SKIPPED no git repository found.Does this mean I cannot use this command on my localhost repo?
tim
Fri, 01/13/2017 - 09:56
Permalink
No problem :)Some of the CLI
No problem :)
Some of the CLI functions require git to be initialized in each of the libraries. You could create a folder elsewhere on your system where you can git clone the h5p libraries from github. This would ensure that the libraries would have be git repositories. You can then work on these files with the CLI, use the h5p pack function to zip them up and then reupload them to your wordpress site.
Most of the guys + girl here (in the Core Team) use drupal for development as it comes with a development environment for h5p that doesn't require h5p pack every time. Let me know how you get along.
papi Jo
Fri, 01/13/2017 - 09:47
Permalink
Yes, I just found out about
Yes, I just found out about the GIT requirement thanks to an extended private exchange with Tom. I have set up Drupal on my localhost machine, and now I can use the command
add-english-texts
. I also read carefully the instructions at https://h5p.org/development-environment.One problem with such development instructions or tutorials is that they are written by people who know what they are talking about rather than for people who don't know much. Which explains why some requirements are so obvious to developers that they don't even think of mentioning them, e.g. "install git".
My life-long experience as a language teacher plus my experience as an amateur developer and tutorials writer has convinced me that it is not so easy for someone who knows to explain things to someone who doesn't. Fortunately we can get lots of help here in the forum from people like you and other members. Thanks again!
tim
Fri, 01/13/2017 - 09:55
Permalink
I agree! A lot of the
I agree! A lot of the documentation could be written much clearer, especially with non-developers in mind. We need to do a lot better.
Keti K
Sat, 03/17/2018 - 15:29
Permalink
Column - language adaptation
Hi there,
I have created content with the column (using different content types: single choice, true/false, image hotspots, etc.) but seems like I can't do language adaptation (translate English into the language I need) on the buttons 'retry', 'show solution', 'check' and such. I can do translations when choosing each of the content types separately, so is it restricted when you use column only?
Many thanks
BV52
Mon, 03/19/2018 - 07:43
Permalink
Hi Keti,Where are you
Hi Keti,
Where are you creating your content? What language are you trying to change it to? Also there shouldn't be any difference when using Column or the stand alone contents.
-BV52
apienk
Fri, 03/15/2019 - 12:26
Permalink
Error
I'm getting this error when trying to create a new language file. Note: My GIT is not initialized. Any ideas?
sudo h5p create-language-file h5p-question-set pl fs.js:115 throw err; ^ Error: ENOENT: no such file or directory, open 'h5p-question-set/language/pl.json' at Object.openSync (fs.js:439:3) at Object.writeFileSync (fs.js:1190:35) at /usr/lib/node_modules/h5p/lib/h5p.js:1532:8 at readJson (/usr/lib/node_modules/h5p/lib/h5p.js:815:5) at readSemantics (/usr/lib/node_modules/h5p/lib/h5p.js:844:3) at Object.h5p.createLanguageFile (/usr/lib/node_modules/h5p/lib/h5p.js:1530:3) at Object.handler (/usr/lib/node_modules/h5p/bin/h5p-cli.js:608:11) at Object.<anonymous> (/usr/lib/node_modules/h5p/bin/h5p-cli.js:874:24) at Module._compile (internal/modules/cjs/loader.js:689:30) at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)icc
Mon, 04/29/2019 - 16:19
Permalink
You need to make sure the h5p
You need to make sure the h5p-question-set/language folder exists, e.g. using ls h5p-question-set/language before running the command.
And if I remember correctly, you will probably need to have the .git in the library in order for the command to recognize it.
Or Daniel
Sun, 06/23/2019 - 20:08
Permalink
Hebrew Translation
Hi,
There is an amazing translation project to Hebrew (RTL) led by Nadav Kavalerchik
Here is the link on Github https://github.com/iucc/h5p-moodle-plugin?fbclid=IwAR2I1KCYnKcU0PMBL5Yc8qZJxOVoNj-46BSL51NOQ6GlylrbrPq4bUO1RnA
and the link to the project https://deutsche-h5p-uebersetzungscommunity.tk/languages/he/h5p/?fbclid=IwAR3xbu86dzNOWz1GDFAtGVFIUhl69-X5KaSMZGH2DacreDp7N9oAfQmIAO8
I wanted to know if it's possible to use in WordPress as well? and do you have a tutorial that I can send to teachers to use? any help will be greatly appreciated.