opera-romana-pellegrinaggi / indesign-translate-indd

script that will extract stories to a translation.json file, and import stories from translation.json files

indesign-translate-INDD

Scripts that will extract stories to a translation.json file, and import stories from translation.json files

ExportStoriesI18nJson

This script will extract all strings from an Indesign file and save them in nested JSON format to a translation.json file, which is easily consumed by translation tools such as weblate. The folder where the translations are extracted to will be saved as a label attached to the Indesign file, after which the Indesign file will be automatically saved so that the label will stick.

N.B. Any time the source file is changed in any way, this script must be run again, so that the translation.json is regenerated. This is the only way to be sure that the keys for the translation strings will match and be correctly imported again.

ImportTranslation

Once translations are complete, this script will scan the translations folder (as saved in the label attached to the document by the previous script), and let you import either a single language translation or all language translations. The translated strings will be imported in place of the source strings, and a new Indesign document will be created in the current folder with the language flag added to the name of the document.

Setup

Place these scripts in your Indesign script folder. On Windows, this is something like: C:\Users\{username}\AppData\Roaming\Adobe\InDesign\{version}\{language}\Scripts\Scripts Panel\. The scripts should then appear in the scripts panel under User. In order to access the scripts panel, check Window >> Utility >> Script.

Also, make sure to add the es5 and es6 shims to the parent folder. Adding them to the parent folder will prevent them from showing in the Scripts Panel. References to these shims are hardcoded in the scripts to the parent folder for this reason.

These shims can be found here:

• ES5: https://github.com/ExtendScript/extendscript-es5-shim/blob/master/index.js
• ES6: https://github.com/ExtendScript/extendscript-es6-shim/blob/master/index.js

Make sure to use only the shims from these two repos, you cannot use other kinds of ES5 or ES6 shims which are meant for web development. These two repos contains shims aimed specifically at Extendscript (which has no DOM, so cannot have any references to the document object).

Save them in the parent folder (on Windows, something like C:\Users\{username}\AppData\Roaming\Adobe\InDesign\{version}\{language}\Scripts\) with the names es5-shim.js and es6-shim.js.

With the ES5 shim, there is no need to include a JSON shim separately. It is already included in the ES5 shim.

Things that the graphic designer should keep in mind when designing the source file

• For each story expand the story editor to take up the full width of the screen, and turn on the end of line symbol in the story editor. We want to make sure that each sentence that should be translated as one sentence does not have an unnecessary line break.

• Avoid adjusting the format of specific pieces of text within a story as this causes that piece of text to have to be translated seperately from the rest of the sentence, in order to maintain the formatting.

• For the same reason DO NOT USE KERNING. Kerning results in each indivual letter needing translation.

• If the source document is written in English, keep in mind that English is a relatively compact language. For short peices of text assume that other languages could be up to 300% more characters, and for longer sections up to 170% more characters.

• Again if the source document is written in English, remember to expand text boxes as much as possible to support more characters than is in the English version.

indesign-translate-indd's Issues

are hyperlinks included in stories?

I have a feeling that hyperlinks may need to be picked up separately from stories and TextStyleRanges. Should double check this to make sure hyperlink text is translated if need be.

how to deal with newlines

If I try to extract stories, then paragraphs within stories, then TextStyleRanges within paragraphs, the only drawback is that some TextStyleRange objects can span across more than one paragraph. So we wind up having duplicated text to translate.

To prevent this, I have completely skipped the paragraphs, and gone straight from stories to TextStyleRanges within the stories. However, we now have a series of \r and \n characters to deal with. And weblate has a hard time dealing with these. If the source has a carriage return, and in the translation we add a newline, weblate will complain about mismatched newline characters.

If I try to convert all newline and carriage return characters to their html entity representation (i.e. 
 and 
), this still isn't handled very well for translation, because there is no "click to copy" from source to translation (as I had hoped). So they kind of make for dirty translation strings.

I suppose I can try to split strings on \r carriage return characters (which I believe correspond with New Paragraph in Indesign? and \n newline characters correspond with soft newlines?). Then we could just join them back up with an \r character when importing translations. And \n should be easier to handle in weblate so shouldn't be so much of a problem...

The only possible problem here is if there are stray \r characters at the end of a string. Then on splitting, we would have a second string that is empty. Would it still show up in the weblate interface? Might need some trial and error for this to work...