Professional providers translating Asciidoc

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

Professional providers translating Asciidoc

davidgamba
Hi guys,

My team at work is using Asciidoc to build our documentation manual. Our ability to continue using Asciidoc depends on whether or not the sources can be translated into several languages by a translating vendor (Otherwise we have to move into a less flexible proprietary tool).

Do any of you have any experience in this area? Can any of you point me towards a company that has translated Asciidoc before?

I appreciate the help,

--David
Reply | Threaded
Open this post in threaded view
|

Re: Professional providers translating Asciidoc

mojavelinux
Administrator
My current recommendation is to handle translations using DocBook. Most teams I know of using AsciiDoc do it this way. Translation text gets extracted from the document source, so it doesn't matter as much at that point what language the source document is in. There are plenty of enterprises offering translation for DocBook.

Once you have the translations for DocBook, you could either publish using DocBook or convert back the translated document back to AsciiDoc to publish using Asciidoctor tooling. (using something like docbookrx - https://github.com/opendevise/docbookrx)

Honestly, I don't really see why it would be a big deal to translate AsciiDoc if you can find a group that does it for Markdown (or even if they don't do Markdown). The process will be very similar. It's just plain text.

We do plan to add gettext extraction capabilities in the Asciidoctor ecosystem. I just haven't been able to spend time on it yet. All the work we are doing to parse the AST is clearly a prerequisite for being able to generate po files directly from AsciiDoc source with perfect accuracy...then subsequently weave the translated text back in when it's available.

The idea is to be able to leverage the existing translation tools while still working with AsciiDoc. The only thing the translator would need to be aware of is perhaps the inline markup. My understanding is that they are already well aware of that concept. Having said that, there's still a lot to explore and understand, I realize.

Cheers,

-Dan

On Thu, Jan 22, 2015 at 1:21 PM, davidgamba [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hi guys,

My team at work is using Asciidoc to build our documentation manual. Our ability to continue using Asciidoc depends on whether or not the sources can be translated into several languages by a translating vendor (Otherwise we have to move into a less flexible proprietary tool).

Do any of you have any experience in this area? Can any of you point me towards a company that has translated Asciidoc before?

I appreciate the help,

--David


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Professional-providers-translating-Asciidoc-tp2692.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Professional providers translating Asciidoc

davidgamba
I am using Asciidoctor PDF to generate the final PDF. I don't know if I can go directly from Docbook to that without using the fopub converter. I will have to test the docbook to adoc converter to see how that goes.

I will meet with the engineer of the translation company, if they agree to use the adoc source directly I will put their info here since they deserve the good press.

I will keep you posted, thanks for the reply.

--David
Reply | Threaded
Open this post in threaded view
|

Re: Professional providers translating Asciidoc

mojavelinux
Administrator

On Mon, Jan 26, 2015 at 12:03 PM, davidgamba [via Asciidoctor :: Discussion] <[hidden email]> wrote:
  I will have to test the docbook to adoc converter to see how that goes.

That's probably the route you need to explore in the short term.
 

I will meet with the engineer of the translation company, if they agree to use the adoc source directly I will put their info here since they deserve the good press.

Cool!

Cheers,

-Dan

--
Reply | Threaded
Open this post in threaded view
|

Re: Professional providers translating Asciidoc

davidgamba
So we discussed the possibility of translating the outputs but it really made no sense financially (we have several brandings of the product so we would need to send each of them for translation or add overhead to the process). We will have to send the content for translation using the proprietary software that we have.

The question then came about distributed workflow. My team is productive generating content in Asciidoc and the ease of use means everybody is actually generating some content. The cost of the other tool means only our doc writers will have a license for it so we might have to maintain two formats so we don't loose the gained productivity.

The other tool comes with a contributor license but it only allows for comments, so the contributor can't generate an entirely new section or properly format an existing one. Only the full license can do that.

How about if I help to start creating a XLIFF converter for Asciidoc? It won't be ready in time for me to use it but it might be of help in the future. Is this the way you were planning to go about with translations?

--David
Reply | Threaded
Open this post in threaded view
|

Re: Professional providers translating Asciidoc

mojavelinux
Administrator

On Fri, Jan 30, 2015 at 9:32 AM, davidgamba [via Asciidoctor :: Discussion] <[hidden email]> wrote:
How about if I help to start creating a XLIFF converter for Asciidoc? It won't be ready in time for me to use it but it might be of help in the future. Is this the way you were planning to go about with translations?

I'm sure such a translator would be helpful to a certain audience, but personally, I'd rather avoid proprietary solution anywhere in the toolchain. I still don't have an exact answer for how we're approaching translations, but I continue to soak up input so that we solve it in the most practical way. Learning other languages (including French) is helping to put me in the mindset of translators, which I think will be key to devising the right solution.

Cheers,

Reply | Threaded
Open this post in threaded view
|

Re: Professional providers translating Asciidoc

ciampix
Sorry I have seen this just now (I still prefer using the mailing list).

My current recommendation is to handle translations using DocBook.

You have a tool that produce wonderfully well pdf avoiding messing with DocBook (asciidoctor-pdf) and suggest to use it for translations? Why?

Most teams I know of using AsciiDoc do it this way.
Example of not using docbook for translation of asciidoc docs: KiCad

http://kicad-pcb.org/
http://kicad-pcb.org/help/documentation/
https://github.com/kicad/kicad-doc

just a little but powerful command: po4a
Then you can use all the tools you prefer (there are many) to translate the generated po files.

Honestly, I don't really see why it would be a big deal to translate AsciiDoc if you can find a group that does it for Markdown (or even if they don't do Markdown). The process will be very similar. It's just plain text.
You probably do not see this as a big problem since you consider translation as a single task, but, especially with software, translation is like developing: it is a constantly running job. You have to update translation while docs are written and modified. You really do not want to re-read constantly all the text to figure out what have changed and how for every language. You want something that extract automatically untranslated/changed strings for translation. You want gettext support. In this po4a comes in just as the perfect tool.

Regards
Reply | Threaded
Open this post in threaded view
|

Re: Professional providers translating Asciidoc

mojavelinux
Administrator

On Wed, Apr 27, 2016 at 12:35 AM, ciampix [via Asciidoctor :: Discussion] <[hidden email]> wrote:
You want something that extract automatically untranslated/changed strings for translation. You want gettext support. In this po4a comes in just as the perfect tool.

That's my goal for Asciidoctor. I just haven't had the opportunity to delve into solving that problem yet. That's why we have:


At some point, I experimented with a prototype. Out of that experimentation came the extensions API in Asciidoctor. I haven't come back full circle to using that extensions API to implement po4a integration. There's only so many hours in the day ;)

Cheers,

-Dan


--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Professional providers translating Asciidoc

bwklein
In reply to this post by davidgamba
Please see the post I just made today where we are looking to use CrowdIn.com and our existing team of translators for our software documentation and website content.

http://discuss.asciidoctor.org/Using-CrowdIn-com-for-AsciiDoc-translation-tp4657.html

We have not used this feature of CrowdIn yet, because we have our own translator network, but you can invite paid translation vendors into your projects too.

-Bryan