oxygenxml / oxygen-dita-translation-package-builder-addon

This plugin is a helper for sending DITA files to translation.

DITA Translation Package Builder

This add-on contributes contextual menu actions that help you build a translation package for DITA files that can be sent to translators. You can also extract the changed files back into your project once you receive the package back from the translators.

Once installed, a sub-menu named Translation Package Builder is available in contextual menu of the DITA Maps Manager with the following actions:

1. Generate Milestone - This action is the first one to use. It will generate a unique hash for each documentation resource. This information will be used by the second action to detect which files have been modified. A milestone file should be generated after you install this plugin and then again after each package is sent to translators.
2. Create Modified Files Package - This action detects which files have been changed since the last generated milestone. These files are packed inside a ZIP file that can be sent to translators. After doing this, you can also generate a new milestone so that the next package will only contain new changes.
3. Apply Package - When the translated files arrive from the translator, you should open the DITA map that corresponds to the received language (e.g. open dita-map-french.ditamap if the package contains the french translation). Invoking this action will extract the changed files inside the map's directory.

How to install

1. In Oxygen, go to Help->Install new add-ons to open an add-on selection dialog box.
2. Enter or paste https://raw.githubusercontent.com/oxygenxml/Translation-Package-Builder/master/build/addon.xml in the Show add-ons from field.
3. Select the DITA Translation Package Builder add-on and click Next.
4. Read the end-user license agreement. Then select the I accept all terms of the end-user license agreement option and click Finish.
5. Restart the application.

Result: A Translation Package Builder submenu will now be available in the contextual menu of the DITA Maps Manager. This submenu includes actions to generate a package of modified files that can be sent to translators, as well as an action to extract translated files back into your DITA project.

Video presentation showcasing the Translation Package Builder functionality: https://youtu.be/dEWc2HIHvbk?t=1957

Copyright and License

Copyright 2018 Syncro Soft SRL.

This project is licensed under Apache License 2.0

oxygen-dita-translation-package-builder-addon's Issues

Apply profiling conditions when building the ZIP archive with the modified files set

Feedback from one of our end users:

       We would like to be able to export new/changed files that are specific
       to a selected root map, with profiling condition filters taken into account.

My question:

        If a common topic has inside it content belonging to Product A and Product B (for example two paragraphs, one which appears only in A and one which appears only in B), for Product A do you want to send that common topic to the translator with one of those paragraphs filtered out?

Their answer:

       Not necessarily. The complete topic with all of the conditional content could be translated at once, as long as it’s ready.

So when creating the ZIP besides selecting the milestone file the end user would like to also apply a profiling condition set to filter out additional resources.

Ignore the contents of the _MACOSX folder when applying the translation package

If the translator is on Mac, when it zips the translated resources, a _MACOSX folder will be present inside the archive. We should ignore this folder when we collect the resources in the package.

Generated XHTML report is invalid

It seems to be missing a "head" element.

Use a thread when generating the milestone

It may take a lot on larger DITA projects like:
https://github.com/oxygenxml/userguide

Maybe show an undetermined progress while the milestone is computed.

Milestone creation failed due to: Please select a directory

One of our users tried to use the plugin to create the milestone. They received the message specified in the issue title.
Additional info from them:

I work with an SVN checkout to local disk (D partition, extra SSD), so the files are local. No server connections.

A couple of observations, the problem is probably the 3'rd one:

1. The "computeResourceInfo" method is recursive, so if at some point you cannot list the contents of a folder, this does not mean that you cannot list the contents of the original folder where the DITA Map was located, maybe you cannot list the contents of some subfolder which does not have access rights.

2. The exception message does not help, it would help if it told you for what folder it has listing problems. And maybe in cases when it cannot list some subfolder it could just issue a warning (maybe in the results view) and continue preparing the package. Or gather all these errors instead of throwing them and breaking the recursive method, then present them at the end.

3. When converting from URL to File instead of this:

     URL editorLocation = editor.getEditorLocation();
      final File rootDir = new File(editorLocation.getPath()).getParentFile();
   

try to use our API instead:

      ro.sync.exml.workspace.impl.util.AccessUtilImpl.locateFile(URL)

What happens is that if the DITA Map is in a folder with spaces, the path to the DITA Map is escaped like:

     file:/D:/projects/eXml/samples/dita%20-%20Copy/flowers/flowers.ditamap

and if you do this "new File(editorLocation.getPath()).getParentFile()" you will obtain a file looking like this: "D:/projects/eXml/samples/dita%20-%20Copy/flowers/". So the URL path needs first to be unescaped with the %20 converted to spaces and then a file needs to be created from it. That's what our API does.

Modification in main DITA Map does not seem to be detected

I create the milestone. I modify the main DITA Map, I add an extra topicref to an existing topic, I try to create the package containing changes, the plugin says that there are no changes.

Specify which type of files to include into the package

@xephon2 said on #8

Pulling external SVG images referenced in topics would be nice. Quite difficult to determine what to translate or not, e.g. referenced source code should not. Maybe handing this via config would be useful, e.g. by MIME and/or extension.

The root map might not be in the top folder

Currently, when building the milestone file, as well as the package, we assume that the map is in the top folder. Sometimes, the structure of the project is something like this:

-root
--topics
----a.dita
--images
----a.png
--maps
----my_map.ditamap

The milestone file

If we analyze the map structure (see #8 ) then we will know all the resources and we can infer the root folder. We can:

1. put the milestone file next to the map as we do now
2. since multiple maps can reside in the same folder we can name the file milestone-myMapName.xml
3. keep in the milestone file the information about where the root folder is (as a relative path):
   <resources rootFolder="../../">

The package

We probably have to put the milestone file inside the package. This way, when it returns and the user applies it over the map, we can extract the root folder from it:
<resources rootFolder="../../">

Create modified Files package ends with "Unable to copy file: ..."

Hello,
selecting to create the modified files package seems to run smoothly, except it creates an empty zip file and the log contains the error message "Unable to copy file...". I closed the modified files in Oxygen before starting the translation package creation, but apparently that was not the cause. Any idea? Regards, Christian

The @date attribute inside the milestone file is not properly computed if file already exists

If the "_milestone.xml" file already exists on disk, when I attempt to overwrite it the new milestone file will have the @Date attribute value set to the current file's modification time instead of having it set to the current date.
In the "ChangePackageGenerator.generateChangeMilestone(IRootResource)" there is an XXX.

More friendly messages

For example after I tried to create the ZIP of changes but there were no differences from the last milestone:

Package creation failed because of: java.io.IOException: There are no changed files since the milestone created on: Thu Aug 10 15:14:54 EEST 2017

Ideally the exception name should not be presented in the message.
Maybe something like:

   Could not create package.
   There are no changed files since the milestone created on: Thu Aug 10 15:14:54 EEST 2017

Feature Request: Check if files have been deleted

A request from our localization department.
It would be great if the Translation Package Builder could check if files have been deleted since the last milestone was created.

Generate a translation report

When creating the package we should offer the possibility to create a report with all the changed resources. The action should present a dialog with a browse part in which the location of the package is selected and a check box to choose whether the report is created or not.

The report is saved automatically next to the map, it has a predefined name and contains the relative paths of all modified resources. After we created we will also open it inside an editor. We can use XHTML as the format.

Prerequisites for applying package?

I translated a package using Madcap Lingo, exported the translated DITA files, created a ZIP of it and stored the ZIP in the DITA project folder.
When applying the ZIP on the .ditamap I get the following error messages:

1st error: Failed to apply package because:invalid CEN header (bad entry name)
2nd error: Failed to apply package because:Cannot invoke "java.util.List.Iterator()" because "filePaths" is null.

So something about the ZIP or the files exported from Lingo do not meet the add-on's expectations. What should the ZIP contents look like or rather what are the prerequisites for applying the package?

Feature request: Support command-line usage

I'd love to be able to automate this as part of a CI/CD process; to do that, I need to be able to call this from the command-line.

Appling the package when the translated map doesn't exist

When applying the package we could present a dialog:
"Where should I apply the translated resources?"
"- on the current map: [my_map_fr.ditamap]"
"- in the directory: [Browse]"****

The second option will help when you are translating a map to, let's say French, for the first time and you don't have the "French" version of the project yet.

Problems using the package builder

The ZIP file was not generated because of two xrefs that were reported as modified files in the xhtml report:

topics/status_information_on_bed_view_2.dita#status_information_on_bed_view_2/table_ufb_hg2_cy
topics/status_information_on_bed_view_2.dita#status_information_on_bed_view_2/table_rvn_c4k_by

When I manually removed the xref in the source topic, the ZIP file was generated immediately. Note that there was no error message when the ZIP file was not generated.

Another improvement could be to generate the ZIP file even if some files are missing and report them. I tested the add-on on a sample project (exported from a real ditamap) where some topics were missing because they were only called through xref references and not in the ditamap (I'm not saying that's a good writing practice...). I had an error message that the files were missing. IMHO, it could be interesting to generate the ZIP file anyway and report the missing topics.

Implement output to COTI packages

Hi,

could you please implement a real COmmon Translation Interface (COTI) conform package export/import? COTI is a "German standard" of the DERCOM association, see DERCOM - Projekte. COTI is actually a ZIP file with some XML metadata. You can download the spec in a ZIP file from the above mentioned URL.

Thanks a lot,
Stefan

Create modified resources package should also be able to create the milestone file

We got feedback from one of our end users:

    In addition, we would like the first milestone to be created automatically when 
    we create the first zip package. 
   Yes, the first time I choose “Created modified files package,” besides building the ZIP, 
   Oxygen should also create the first milestone.

So when the user attempts to create a ZIP but they have not yet created the milestone file maybe they could also be prompted if they want to create the milestone file.

Integrating external files into milestone.xml and the modified files package

We use many shared external topics that contain, for example, only parameters (plentry elements). The topics are not connected to any ditamaps, but the parameters are referenced (conrefed) from files that are connected to the main ditamap. The reason we do this is that we use the parameters in various orders in multiple topics, so we cannot create one topic with all parameters and reference those from the other topics.
These external topics are usually also exported if we use the Export DITA Map function in oXygen. When creating a milestone or a modified files package, these shared external topics are unfortunately ignored.

Allow translation of plugin messages and labels to multiple languages

We have API for this:

oxygenxml/oxygen-docbook-validate-check-completeness#9

Generating milestone based on the Map structure.

Sometimes, in the same directory, you can find the documentation for multiple products. Let's say that we have productA.ditamap and productB.ditamap in the same directory. There is no way to send to translation just the resources for Product A because we have just one milestone file that contains the hashes for all resources.

We could iterate over the current map structure and its topics and collect all the referred resources (topics, images etc). Basically everything that is referred using an href attribute.

Implementation ideas: We might create an abstraction on the current resource iteration with multiple implementations:
--The current file system interation
--The map iteration based on AuthorNodes (the map is loaded inside the DITA Maps Manager so we can take advantage of that)
--The iteration over the resources referred in a map (the DITA Map model doesn't load the referred topics so we have to parse them on SAX)
Also, a topic might be referred multiple times so we should take care take care not to process it more than once or fall into a infinite loop .

Feature request: Possibility to specify milestone file to be applied for package generation

I'd like to have the possibility to do that, as I have a habit to add date to the name of the milestone files.
When trying to generate the tr. package it results in the Milestone Missing message :-(
Sometimes it is handy to pick an older snapshot of the docs to generate a package.
Piotr

Issues when creating milestone/archive

1. After creating the milestone there is a message like "Milestone created at: ". Maybe you can put there the full path, including the XML file name. Maybe also use our API to show the information dialog. Using our API if the message text is long it will be automatically wrapped.

2. If the milestone file is already there, maybe you could ask the end user if they want to override it.
   Ideally the milestone XML would also contain an XML element holding the date when it was created. In this way when you want to overwrite the file, you could tell the end user that an older milestone XML created at "August YYYY" is already on disk.

Maybe we could somehow also allow the end user to specify a name for the milestone file. So after calling the action to create the milestone, have an intermediate dialog in which you explain what the milestone file is and in which the end user can pick a folder and file name where it should be saved, by default of course we offer the DITA Map folder and the default file name.

Plugin breaks when a referred image file is missing

In my map structure I have an external reference to a missing image file.
When the "Generate Milestone" is called, the plugin fails to generate the translation report.
Error is :
Milestone creation failed because of: path/to/file/imageName.png
(The system cannot find the file specified)"

Issues when creating modified files package

I press the action, the dialog shows. If when showing the dialog we already know the modified files I would kind of like a label in the dialog saying something like:

"A number of X files was modified since the last time the milestone was computed. More details..."
And pressing the "More details" could maybe show the list of files which will be packed in the zip... maybe...

Choose place where to generate the milestone file

Feedback from one of our end users:

I kind of misuse your translation package builder to create baseline files for my maps in order to identify changed topics after a given time. This is quite handy for me. Now I wondered, if the storage place of the baseline files can somehow be configured. Right now, these files are created where the map is. Because I already have many maps in my root folder, these extra files “pollute” the order of the maps. My approach is to create the baselines, move them to a directory and move them back when I create the change report. Somehow too much fiddling …

Clicking the "More details" link from "Package location dialog" shows dialog with wrong parent

Regenerate the milestone when creating the package

The current flow is this:

1. Generate the milestone
2. Work on the files
3. Create the package for translation
4. Regenerate the milestone

Someone suggested to regenerate the milestone automatically when the package for translation is created, thus merging steps 3 and 4. I can see the benefit as someone might forget to manually regenerate the milestone. If that happens, the next package for translation will unnecessarily contain some files already translated.

The only benefit of having this separate step is if you misplace/delete the package. If we automatically regenerate the milestone, you wont be able to create the package again.

Let's have an option controlling this behavior. It remains to be seen what the default value will be.