Best practice: Translation of Asciidoctor documents

Hi,

I'm looking for experiences with translating Asciidoctor documents into different languages.
So far we've been using word documents that are translated via Trados. It comes with a translation memory, so identifying new or changed content was part of the translation process within Trados.

Is someone already doing that with Asciidoctor files as a source? Has somebody already created a Trados filter that handles asciidoc or asciidoctor syntax? A simple approach would be to send an entire asciidoctor document as well as a pdf version to the translation agency. The pdf would help them to see the formatting. Using the chrome extension might also be an option.

What I've found so far is this feature request: https://github.com/asciidoctor/asciidoctor/issues/788
The Neo4J project seems to use a set of scripts that make use of Po4a. My current understanding is that this toolchain  helps to identify untranslated or changed content, to create a changeset and it helps with merging the translated content. Is anyone using this in production on a regular basis? My impression is that a gettext-based approach is adding a lot of overhead if you're writing technical documentations or books with Asciidoctor. A translator usually needs the context of the paragraph to translate it correctly. So splitting it up into very small chunks doesn't feel right.


Thanks!
Christoph

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Best-practice-Translation-of-Asciidoctor-documents-tp2309.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Hi Dan,

thanks for your input. I'll let you know how we proceed and if we invest in a asciidoctor filter for Trados or not. Others might be able to benefit from it as well. Our translation agency is currently evaluating how much work that will be.

I agree that the workflow is key, our situation is like this:

We maintain about a dozen products. We provide a documentation in two languages (german, english). Page sizes vary between 20 - 200, depending on the complexity of the product.
At the moment, we greatly benefit from the translation memory system in use. We write the documentation (in german). The "release candidate" gets copied into an english version and all screenshots are replaced with their english counterparts. Both files are send to our translation agency. It takes usually 1-2 weeks to get the translated version back.
We usually make minor changes during that time to the original version, based on the feedback of internal testing etc. The nice thing about the translation memory approach is that we don't need determine which parts have changed. We just need to know that we have changed something. If the updated original version will be reimported by our translation agency and the translation memory system automatically "translates" all unchanged content.

We use the same approach for regular maintenance releases. We do skip the translation agency for minor changes and translate them on our own in favor of a faster release cycle. This means that the translation memory system is not aware until we send the updated file to our translation agency. The will translate the minor changes a second time, which might differ from our translation, but that hasn't been an issue.

In the past that approach worked well with word documents. I expect it to work with asciidoctor files as well. That said, I'd classify our requirements as very basic and simple. A batch approach is sufficient for our needs.

I'm not sure if a more incremental approach is needed for other scenarios or not. Our main product is a content mangement system and batch approach is certainly not feasible for bigger customers for several reasons. You certainly have a better understanding how asciidoctor is used and if they are valid in that context or not:

1) New content is created all the time
2) number of editors is certainly higher than for a documentation or a book
3) time to production does matter more for "websites" than for technical documentation or books
4) the number of languages might be higher. For our customers it's common to have more than 20 languages.

That usually results in requirements like:

a) the translation part needs to be part of the larger "content creation workflow", which includes a review of the original version as well as the translated version.
b) it's common that the original version changes will being in translation. Depending on the content, it might be ok to release a outdated version to production or not. Critical content might need to be correct and up to date all the time. Non critical content can be outdated. Better outdated than not available.
c) a dashboard is needed to see all modified content that needs translation, all content "in translation", translation that need to be reviewed and imported.
d) You usually don't want to send every single change to the translation system immediately. It's much cheaper to queue up a number of smaller changes until and translate them at once.



Using git as a cornerstone of a "workflow" sounds good. You want to keep the documentation close to the source and build the documentation during the build process. It might be possible to use git best practices for certain parts of the workflow (feature branches, pull requests + approval for reviews, merging).

XLIFF (http://en.wikipedia.org/wiki/XLIFF) might be a good alternative to gettext/po. Version 2.0 has some great enhancements. Most translation tools already support XLIFF. The Okapi framework provides a library and an  open source toolstack that help translators (http://okapi.opentag.com/). Commercial tools support XLIFF as well. I'm not a translation expert but it seems to be more suitable for longer documents/books than gettext.

Christoph

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Best-practice-Translation-of-Asciidoctor-documents-tp2309p2325.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Wow, thanks for the amazing feedback! I'm going to link this discussion to the issue so that it will serve as requirements for the feature and help shape it.

-Dan

On Wed, Oct 8, 2014 at 4:18 PM, cfeddersen [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi Dan,

thanks for your input. I'll let you know how we proceed and if we invest in a asciidoctor filter for Trados or not. Others might be able to benefit from it as well. Our translation agency is currently evaluating how much work that will be.

I agree that the workflow is key, our situation is like this:

We maintain about a dozen products. We provide a documentation in two languages (german, english). Page sizes vary between 20 - 200, depending on the complexity of the product.
At the moment, we greatly benefit from the translation memory system in use. We write the documentation (in german). The "release candidate" gets copied into an english version and all screenshots are replaced with their english counterparts. Both files are send to our translation agency. It takes usually 1-2 weeks to get the translated version back.
We usually make minor changes during that time to the original version, based on the feedback of internal testing etc. The nice thing about the translation memory approach is that we don't need determine which parts have changed. We just need to know that we have changed something. If the updated original version will be reimported by our translation agency and the translation memory system automatically "translates" all unchanged content.

We use the same approach for regular maintenance releases. We do skip the translation agency for minor changes and translate them on our own in favor of a faster release cycle. This means that the translation memory system is not aware until we send the updated file to our translation agency. The will translate the minor changes a second time, which might differ from our translation, but that hasn't been an issue.

In the past that approach worked well with word documents. I expect it to work with asciidoctor files as well. That said, I'd classify our requirements as very basic and simple. A batch approach is sufficient for our needs.

I'm not sure if a more incremental approach is needed for other scenarios or not. Our main product is a content mangement system and batch approach is certainly not feasible for bigger customers for several reasons. You certainly have a better understanding how asciidoctor is used and if they are valid in that context or not:

1) New content is created all the time
2) number of editors is certainly higher than for a documentation or a book
3) time to production does matter more for "websites" than for technical documentation or books
4) the number of languages might be higher. For our customers it's common to have more than 20 languages.

That usually results in requirements like:

a) the translation part needs to be part of the larger "content creation workflow", which includes a review of the original version as well as the translated version.
b) it's common that the original version changes will being in translation. Depending on the content, it might be ok to release a outdated version to production or not. Critical content might need to be correct and up to date all the time. Non critical content can be outdated. Better outdated than not available.
c) a dashboard is needed to see all modified content that needs translation, all content "in translation", translation that need to be reviewed and imported.
d) You usually don't want to send every single change to the translation system immediately. It's much cheaper to queue up a number of smaller changes until and translate them at once.



Using git as a cornerstone of a "workflow" sounds good. You want to keep the documentation close to the source and build the documentation during the build process. It might be possible to use git best practices for certain parts of the workflow (feature branches, pull requests + approval for reviews, merging).

XLIFF (http://en.wikipedia.org/wiki/XLIFF) might be a good alternative to gettext/po. Version 2.0 has some great enhancements. Most translation tools already support XLIFF. The Okapi framework provides a library and an  open source toolstack that help translators (http://okapi.opentag.com/). Commercial tools support XLIFF as well. I'm not a translation expert but it seems to be more suitable for longer documents/books than gettext.

Christoph

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Best-practice-Translation-of-Asciidoctor-documents-tp2309p2325.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--

Dan Allen | http://google.com/profiles/dan.j.allen