Calling anyone with experience localising Adapt courses!
I'm currently looking into ways to make localising a bit easier (e.g. language packs), but would like to hear from people with first-hand experience of this, and get some ideas regarding what would be useful.
Hi Tom
Thanks for starting this discussion. Here's some of my thoughts.
When localising an adapt course, the work is mostly done on the course’s jsons.
Prior to Framework 2.0, there's not much in terms of localisation of the course.json. Only a couple of button texts and extension labels here and there. The rest of the jsons "localisation" happenes anyway for the course content itself.
With Framework 2.0, we have added quite a bit "globals" in the course.json to be localised and additional extension labels, e.g. the Bookmarking extension.
For my current workflow, I localised the course.json in Simplified Chinese and saved it as a sublime text snippet. Whenever I need to develop a course in Chinese, I just replace the content of the course.json from the framework with my localised snippet.
It's very easy to use, quick and effective.
If you don't use snippet, having a localised course.json file as a template and copy it over to the course directory when needed is not much of a hussle. You can find a simplified Chinese version here from my github page.
I think this makes a good start point of course localisation. It'd be great if there's an option in the adapt-cli tool that you can select from a list of languages then download a specific language version of the course.json file rathen than the default English version.
But I don’t think localisation should be stopped here. The next section is my own journey with Adapt and I will give my recommendations at the end.
Since the release of the Authoring Tool, we’ve seen a lot more non-developer but course-designer type of users started to learn and use the tool, myself included.
My adapt experience route is like this:
Started with the Authoring tool -> Encounted Some Techniqal Problems -> Go to the Community Forum and project github page finding solutions -> Not Satisfied with the Authoring Tool (e.g. lack certain plugin support, not very friendly with theme development testing, etc) -> Start to use the Framework.
From my own experience and my observation, it is quite difficult to set up the environment (Framework and Builder) for a non-developer. For a typical eLearning course designer, without prior knowledge of the command-line, it is very intimidating to set up the environment with all the git, node, mongodb etc. set-ups.
This is reflected in the forum discussion. A lot of questions are related to installation problem. And environment setting up is usually the main cause of the problem.
Some people may have stopped at this stage and never have had the chance to try adapt.
Once the environment is set up and running, the course designer started to use the tool to build courses.
Without much prior knowledge of the framework and some key concepts, e.g. ABC, plugins, extensions etc. It was quite a struggle for me to build a sample course containing just a few blocks. My first few attemps failed with some error message. It turned out that the problem is caused by empty components.
It was very frustrating.
Of course, the resources and solutions are out there, you just have to dig them up. Then I went out to the community site, the project github pages for solutions.
This involves quite a lot search and read, all in English.
Also I found the knowledge is quite dispersed, not very easy to quickly locate a solution for your problem. A solution may buried deep down in a thread.
By the way, I was very impressed with the depth of knowledge on this site and the project's github page, the helpfulness and friendliness people shown in this community site.
I found it was not very easy to test theme development with the authoring tool. And some of the plugins I wanted to use were not yet supported in the authoring tool. Then I started to develop course in the framework and this involved more reading and study of diffrent plugins.
Do I think the Framework is more effective? Yes.
But I believe unless you're experienced in editing in source code, it is much effective to use the authoring tool, once you grasp the key adapt concepts, components and extensions, and know your way around the tool's user interface.
Here's some recommendations.
Althoug the above are not all related to localisation, the objective is to build a better user experience nontheless, expecially for non-developers.
Cheers
Sam
Hi Sam,
Thanks for the reply, you make some very good points.
To recap: in terms of actually localising courses (once you've set up your dev environment, and familiarised yourself with Adapt), your work flow is: using a sublime snippet for course.json followed by manually replacing other JSON in the course folder.
A few questions/things to think about:
In response to your points about beginners getting to grips with Adapt, I've started this thread in the Responsive eLearning Forum, as I feel it could do with a separate discussion.
Hi Tom,
That's right. If all I have to do is to translate a course from English to Chinese. I just replace the content in the jsons from English to Chinese. It would be great if there's a tool that you just run a single command to automatically replace the English content from an external translation text file.
Currently, I have no requirement to develop a multilingual course.
I understand the single course limitation of the grunt tool bundled with the open source framework. It wasn't a problem for me since I use Kineo's Native buildkit rub. It's faster and lighter, and build multiple courses.
I wish rub supports multiple themes. Maybe it does, I just haven't found out yet:-)
Sam, I realise this is going way back for you here, but what you wrote is where I am now. I'm an e-learning developer struggling with the way the authoring tool works. For me it needs templates (and lots of them) and tutorials on how to change them. I'm a fan of how the content is laid out I just can't figure out if I can justify spending a lot of time learning the command line and html5 when I have Captivate. Probably one for the future.
Hello Christian
Once you know where to start, adapt theming wasn't that difficult. Here's two wiki articles from the official adaptlearning github repo to get you started:-).
Actually it only require a very basic understanding of the command-line. And you need css knowledge to do the theming.
Please let me know if you have any questions.
Cheers
Sam
Sorry for the late response.
Thanks Tom for starting this threat and thanks Sam Tsiu for sharing your experience with the community.
For LearnChamp, a company located in the heart of Europe, multi-language support is definitely an interesting topic. Many client projects require a huge number of localized courses.
So if Adapt courses can be localised pretty easy, Adapts role in the industry will definitely increase.
Easy Localization:
To make sure that Adapt courses can easily be localized, we must take care that the text is strictly separated from the rest of the markup and code. In short, all text displayed to the learner should be defined in the courses json files (or in another defined source). In my opinion this works pretty well so far. For instance, in the previous version of the boxmenu the “Duration” was hardcoded in the template. In the new Version it is now possible to define this text in the contentObjects.json with the durationLabel attribute. Unfortunately the Assessment / Assessment-Results Plugins seem to only understand the English “infinite” for unlimited attempts. This means that you actually have to change the JS to fully translate courses that use these plugins.
I think that language packs are great for generic elements like button text and aria labels. The issue described previously could also be solved with some sort of dictionary that can be used in the templates and the js code. E.g console.log(Adapt.dict.infinite)
Context is King
In e-Learning content is very crucial. So translation needs to be as exact as possible.
I think this can only be achieved if the translator can get a picture of the whole course instead of translating the content on a sentence by sentence basis.
Would it be possible to use the authoring tool as an interface for translators to edit and translate the course? It might also be possible to create a plugin that allows editing an Adapt course. However saving the changes without a backend will be tricky …
When the text is translated it is also crucial that inline formatting (like: ul, li, strong, i, br, …) will be applied properly.
Content relevant for different countries:
Besides changing the text of components it might actually also be possible that some content is only relevant for some countries. Let’s say you have some content dealing with information about some EU-Laws. Since Switzerland is not part of the EU, parts of the content will differ. It would therefore be nice to define which components are applicable for what countries.
E.g.:
Component A:
…
'body': 'Content related to EU-regulations.'
'countries': ['en-gb', 'de-de', 'de-at']
…
Component B:
…
'body': 'content related to countries not part of the EU'
'countries': ['de-ch']
…
Language Selection
Do we have a decision about how to select the language?
As far as I remember there were two options discussed:
1) Adapt Course contains all languages, select language in the course
2) One individual course per language, select language in LMS
Since both options do have some advantages and disadvantages I think it would actually be nice to go for both solutions.
I think about an automated Workflow like this:
Cheers
Thomas
"Would it be possible to use the authoring tool as an interface for translators to edit and translate the course? It might also be possible to create a plugin that allows editing an Adapt course. However saving the changes without a backend will be tricky …"
The problem here is that the translation agency needs access to your authoring tool installation. For a lot of companies, this will be hosted on an internal server, so outside companies can not access this.
It would be better to send them a package with a published version of the adapt course and a seperate file for translations.
professional translation companies translate text in their own system anyway, so they can track who has translated what, if things have been tranlsated before etc. they might not be willing to work in another system.
Implementing multi-lang courses in adapt.
Currently mulit-lang in adapt is… well it's not really there, when we set this project up we kinda added a couple of lang folders into the course as TODO's for multi-lang where we though we'd come back and implement course based multi-lang. That was some time ago but we never really got there.
Loads of time has passed and my thoughts on this have changed. Implementing multi-lang at the course level may not work. I don’t think we can simply change out the text of the course and place a lang switcher on the index page. Different language courses will most likely have different images, different length of text (which has a knock on effect for styling), it's also possible the entire structure of the course is different, including the theme and the menu.
With that in mind I'd like to propose that each separate language has it's own course, with the course lang stored as a course property. We then build a new top level multi-level lang course that opens with a default language and allows the user to switch between languages.
In that case we would continue building courses as we do today for e.g.
Intro to Adapt (English)
Into to Adapt (Welsh)
Intro to Adapt (Spanish)
Intro to Adapt (French)
We then create our multi-lang course container, and link the above courses into it
Intro to Adapt (multi-lang)
+ Intro to Adapt (English)
+ Into to Adapt (Welsh)
+ Intro to Adapt (Spanish)
+ Intro to Adapt (French)
In the new multi-lang course we would set our default lang, the default lang is the course that loads initially (ideally we'd interrogate the browser for the lang and set that as the default course).
The initial loading page for the multi-lang course contains a lang switcher, in this case 4 languages. When the user can select a different language from the initially loaded course. Essentially the multi-lang course only contains the initial lang-switcher page and then passes control to the selected course (it imports the index page of each of the separate courses).
This means that old courses should be available for this new multi-lang build (there may be some course level lang attributes that we have to add). So it should be a simple add course to the multi-lang container and that most of the development work is contained within the new multi-lang course container and new multi-lang build process.
The low effort way to build this new multi-lang container course is to grab each of the four courses and place them into their own separate lang folder and execute a normal adapt build per course/folder. This has the disadvantage of duplicating the adapt framework multiple times, including any plugins (components/extensions/menus) that are shared through the 4 courses. Assets may also be duplicated through the 4 separate folders. Then grab all of those folders and zip then into a build package with the multi-lang container at the root linking them all together.
The high effort way to implement this would be to have a smart build process that stores the common framework and plugins at a higher level folder and extracts common assets into a shared folder. The individual language folder would then only contain course specific settings, plugins and assets.
The big assumption is that each of the individual courses all contain the same plugin versions and have been built and tested on the same version of the framework.
To implement this in the Adapt Authoring Tool, we'd add another button called something like 'create new multi-lang course'. Once clicked this would present the user with a page where they'd select the courses that they want to include. In this case the build button executes the multi-lang build and packages all the courses into one ZIP file.
Thoughts and feedback welcome.
Good points. Doing multi-lang correctly isn't always straight-forward, for sure.
In my experience, a course would be done in one language, tweaked, perfected, and then it would get translated in another language. Having parity between the languages would be a good starting point, and of course the courses may diverge (not in my experience, however), but I do know that they will share many properties.
A few options:
1) duplicate as the starting point: you lose the parity in the structure if you change the one done in the original language, but at least with most of the work done: setting up the structure and the components and the meta data
2) each element is translatable (including images, videos, audio) a bit like Wordpress using the WPML plugin: this makes it so that if you inject an object in between two objects in one language, every translation gets the object and you just need to update translations (with versioning, you can know that other translations might need an update on an object because one of its languages was updated... A translator could get notified). For styling tweaks, all you need are css classes or js adjustments that detect the language to tweak. You get a nice separation between content and presentation, and no duplicate of the presentation and styling across two versions of a course.
In any case an exported package would probably be needed for each localized version, since the LMS would probably have a way to detect the language, serve the whole experience in the one language up to the launch of the course, and serve the right language for the course upon launch (so the user doesn't have to be asked again about which language to use).
Hello Mark,
due to Christmas vacation my reply is a little late.
I also think if we add “real” multi language support to Adapt we have to make sure that we implement the best solution that enables us to meet all our requirements, even though this means we have to drop existing decisions. Since adapt is developed by a community, we also have to make sure that every collaborator supports the solution we are going to implement.
Therefore I think we should have a Meeting and discuss the different approaches. I am more than happy to set up a hangout for this. More on this in the gitter chat.
We discussed multi language during the developer meetup in Brighton in December and decided to stick to the existing folder structure and add a Language selector at the start. We thought that learners will not switch language half way through the course. Still we need the ability to change the selected language, this might reset the course though. We further agreed to add support to switch text directions and fonts.
With this setup we can use individual assets for each language. Since each language folder contains its own copy of articles.json, blocks.json, components.json, contentObjects.json and course.json we should be able to create a different course structure for each language.
When a learner picks a language, a specific lang property is added to the root html element. This attribute can then be used to add language specific styles to the theme. Since Adapt currently only supports one Menu and Theme per course, we are not able to switch the Theme or Menu for individual languages.
In my opinion this approach fits really well for courses that share many properties, e.g. structure, menue and theme. If the individual languages differ too much, I think it would be better to create one course per language and do the language selection in the LMS.
Besides that we discussed ways to streamline the translation Process. We decided to have a way to export all the text that needs to be translated into a file that can be processed by translation agencies. Once this file is translated, it can then be imported and used to create a copy of the course in another language.
Looking forward to the meeting
Thomas
Hi Thomas, Do you have any update on the localization functionality? Is the best/only method still to translate the course.json content?
Hello Rebecca,
to localize a course you have to translate the course, contentObjects, articles, blocks and components.json files.
As with the next release of the Framework v2.0.11, Adapt offers a languagePicker that allows the learner to select a language from a list of available languages. Each language is a sub-folder in the Frameworks src/course directory containing a localized version of the listed json files above.
Besides that, the framework offers 2 grunt tasks that help course developers with the localization workflow.
The first tasks exports all the Text from the json files into a set of language files (example file). You will then translate these files. With a second task you can import the files. This will create copy of your master course and replaces the text with the content of the language file.
You can test the export / import feature from the official Adapt Framework repository following this steps:
grunt translate:export --format="csv" --masterLang="en"
this creates the following directory inside the framework: languagefiles/en/ containing your language files in csv format.grunt translate:import --format="csv" --masterLang="en" --targetLang="de" --replace
Please make sure to create a proper backup of your files if you test this with a production project!
A detailed documentation is available in the Adapt wiki. Please keep in mind that this feature is not yet released and the documentation is not updated to the latest developments.
Best regards
Thomas
Hi Thomas,
I'm a newer Adapt user, getting acquainted with the localisation feature. So far as I can tell, changing the language mid-stream while taking a course still resets the course progress. Is that the current design still? What are thoughts on not affecting course progress upon a lang change - are there some big challenges for that kind of enhancement?
From a usability perspective, I can see the logic in "Users will only make a language choice once." But the UX voice in my head thinks that some learners would try the change (which is why it's also great you have the warning in there). Then again, it's more likely that I'm just a curious clicker, not representative of most learners ;-)
So far as I can tell, changing the language mid-stream while taking a course still resets the course progress. Is that the current design still?
Yes it is, on the assumption that language 'b' is unlikely to have exactly the same structure as language 'a'. Unless the two versions match exactly in structure, type of components used and have the same tracking ids on the same blocks, applying the tracking data from one language to another will cause tracking errors.
the UX voice in my head thinks that some learners would try the change
That's a reasonable assumption. To mitigate this, I would add some text to the initial 'pick a language' page along the lines of the warning that you get when you try to switch language.
It's worth nothing that - by default - course completion doesn't reset if the user changes language i.e. if I complete the course in English then switch to French the completion status on the LMS will not be changed, it's only the 'internal tracking state' and 'bookmark' that get reset. Equally am 99% certain any score attained previously is retained and would only be wiped if the user takes the assessment again in the new language.
I actually had not considered the possible change in course structure between localisations - really great note there, and a reminder of how localisation can affect things more than we think of ahead of time. The reset makes more sense with that concept in mind.
The only thought that comes to mind is if there's viability in putting something like "_resetOnChange" in config.json's "_languagePicker" property, so that the content authors could decide. The downside, of course, is that setting this to true would only work out if the authors did structure each localisation 100% identically. In the end it would be a lot of work for probably such a minor benefit (allowing language change during the course).
The downside, of course, is that setting this to true would only work out if the authors did structure each localisation 100% identically.
Yep, that's exactly my concern, it really would have to be 100% identical - if someone was to change that option otherwise it would cause a lot of problems.
Also I'm assuming that the Localisation feature will eventually be implemented in the Authoring Tool where I don't think it would be possible to create two structurally identical courses... although saying that it is possible to ensure config options are not displayed within the authoring tool - you just leave them out of the properties.schema.
I'm pretty sure that Ryan Olds said he was going to amend one of his localised courses so that it wouldn't reset on language change (because he knew for sure the languages were identical); so if that is something you need he might well share what changes he made if you ask.
