Picture of Jason Wilson
What is the best process for localising (translating) courses from Adapt Authoring Tool?
by Jason Wilson - Monday, 25 January 2021, 1:03 AM

Hi guys, I've been searching high and low, trying to find the best way to export a course from the Authoring Tool to translate. I can find info on how to do it in the Framework, but how does this translate (see what I did there?) to the Authoring Tool?

I did export my course, but obviously I've not installed grunt etc. into this exported course folder - do I need to do this for every exported course I want to translate, so I can use the grunt "translate:export" command? If so, this seems very laborious. I did install grunt globally when i initially installed the Author Tool - did I perhaps do something wrong?

I think an import/export button would be ideal - export the files straight to csv from the Authoring Tool. Has this been discussed at all?

Any help greatly appreciated! :)

Picture of Chuck Lorenz
Re: What is the best process for localising (translating) courses from Adapt Authoring Tool?
by Chuck Lorenz - Monday, 25 January 2021, 5:17 AM

Jason, you used "Export source," right? So you get the source that includes grunt files that have the "translate" commands.

My understanding is that, yes, you have to install grunt locally in each framework project.  More insight re grunt-cli vs local grunt: https://gruntjs.com/getting-started

an import/export button would be ideal - export the files straight to csv from the Authoring Tool

If you had a button to export only the CSV files, you'd be confronted with getting them back into the course's JSON files. The grunt command translate:import copies the localized values into the correct locations in the proper JSON files. I'm not familiar with your workflow, but it seems you still have a bit of work to do once you've got your CSVs translated. How do you get them in place without using translate:import? 

Having worked with the grunt commands on a number of projects, I haven't found the process to be laborious. Though I admit, there's a bit to wrap your brain around. And I keep a set of instructions to send out to the translators. You don't want them messing with the file format or any data other than the content texts. Save yourself big headaches by being super clear. 

There are a variety of ways to localize a course that's been created in the authoring tool. Here's some:

  1. Duplicate the course while in the authoring tool. Give your translator access to one of the copies and have them replace the texts in situ. (Ensure they don't miss texts in extensions, Project Settings, etc)
  2. Hire a translation company that is familiar with Adapt: Pass the exported source to them and wait for them to return the localized course. (I haven't work with such a company; I know several exist. Matt Leathes or someone else could recommend one.) If you don't need to maintain it regularly, perhaps there's no need to import the localized course into the AT; just run grunt build and zip it up. Also keep in mind that the AT can't handle the language picker yet, so if you want that feature, you'll need to set up your multiple languages outside of the AT. 
  3. Use the grunt localization commands: Export the source from the AT. Extract the zip and open as a framework project. Install grunt locally. Run translate:export. Deliver the csv files to the translator. When the localizations return, run translate:import. Install the language picker if you're going to use it. If not, create separate projects for each language by duplicating the course then deleting the unneeded language folders (e.g. "course/en").

I actually like the grunt export/import commands when working on a framework project. Too often developers make customizations on the fly, adding a text field here or there, and not properly updating the properties.schema where the flag for translatable texts are found. To locate any texts that are not getting exported, I run a test before sending off the CSVs. I run the export and open each CSV in Excel. I use formulas to wrap each value in html (<div style="color:red">). I run the import on these altered CSVs as if it is my new language. Then I go through the course looking for any text that is not red. This saved us from going back to translators on a number of projects.

Picture of Jonathan Briggs
Re: What is the best process for localising (translating) courses from Adapt Authoring Tool?
by Jonathan Briggs - Monday, 25 January 2021, 8:43 AM

Kinda continuing what Chuck said, I've done a lot of this in the recent past. The bigger translation agencies (I had a go at it with Global Lingo) will take exported source code straight out of the Authoring Tool and charge 'engineering' time to extract text strings and put them back again. The trouble with this is you're still going to have to reinstate assets and custom css and it tends (in my experience) to get a bit sticky and picks up little bugs that are time consuming to fix. You're inevitably a bit separated from the person doing the work which is hard going.

The far better way I'd say is to largely follow the process detailed here: https://github.com/adaptlearning/adapt_framework/wiki/Course-Localisation

In this case you export source code; expand zip; get a new terminal window at that folder; run npm install; run grunt build; run grunt translate:export --format=csv

That gives you a language files folder of CSVs that will include html tags. A reasonable translation agency should be able to handle these happily but I'm with Chuck on the guidance front. You need to lay down the law that they don't make any non-language edits or leave cells empty or move anything around etc. I took the view that they should add a translation column rather than giving me back docs I couldn't understand. Obviously that meant I had a bit of work to do to prep for getting the course back together but that's a personal choice. Note also that Excel is not very good here with Latin characters if you're opening translated files. But there's ways around it.

To get the course back together in translated form largely follow the process in the above link but then you'll need to remove the node and language files folders, move over your assets from the original en folder to your new course folder then remove the original en course folders and update your course config, edit names in course.json so that you can identify / manage the course back in the authoring tool. Any custom CSS you had will need to be popped back in when you import as well as establishing start controllers et al.

Then you can zip it back up (zip -r name-of-folder-here ./*) and import it back into the Authoring Tool.

This might sound like a lot, but in reality once you're into the flow you're talking a matter of a 15 mins to do the in / out work. But you do need to have a pretty strong awareness of what's going on as you can cause yourself grief if you get distracted!

What I would not advise (and I was forced into this situation at the start of lockdown last year) is taking the above approach but having to 'manage' files for 'in-house' or 'freelance' translation, where the one-man-band provider has no wider capacity other than straight 'you give me English I give you French' for example. In that situation you get into having to potentially 'clean up' the CSVs to make them understandable and then re-establish everything again. It can be done but no matter how hard you to try to guide it only takes one false move on their part and you're into a whole lot of bother.

Hope this helps get you on your way.

(Limitation: I have not yet done this end to end on the latest FW and AT. There could be tweaks required)

Picture of Matt Leathes
Re: What is the best process for localising (translating) courses from Adapt Authoring Tool?
by Matt Leathes - Monday, 25 January 2021, 10:48 AM
I think an import/export button would be ideal - export the files straight to csv from the Authoring Tool. Has this been discussed at all?

Yes, the thing is that the AAT doesn't - yet - have support for creating 'true' multilanguage courses (one that uses the languagePicker extension). It is on the roadmap but I'm not sure when it will happen.

So, at this point in time, if you want to create a 'true' multilanguage course you need to do that in the framework. You can of course start off in the Authoring tool then export and translate...

As others have mentioned, you don't need to use the translate export/import feature. You can just edit the JSON directly and professional translation agencies like Global Lingo will be familiar with this.

Picture of Jason Wilson
Re: What is the best process for localising (translating) courses from Adapt Authoring Tool?
by Jason Wilson - Wednesday, 27 January 2021, 4:56 AM

Thanks for the reply guys. I'm going to try translating a course soon so will take your comments into consideration. As mentioned above, running the scripts on the exported files isn't really a biggy really, and we have really good translators that have worked with spreadsheets containg code that cant be touched etc., so shouldn't be too hard to get them up to speed.