Page 1 of 1
Are there best practices for setting up Oxygen projects in languages other than English?
Posted: Fri Oct 28, 2022 1:18 pm
by tanja
Hi all,
I was wondering if there are best practices you could point me to regarding the setup of content that is not maintained in English. Up to now, my content was in English. We now got a second product line for which the content is maintained in German, with the option to later translate it into English and French.
My Oxygen project setup follows the recommendations from this post (
https://ivannovation.com/blog/how-to-tr ... -projects/). I also had a look a the add-ons that Oxygen supports here, but my process is not at this step yet.
My main question is regarding the file names and the output in HTML. I still use English names, as our whole SVN structure (which my content is a part of) is using English names. If I now add the de_DE locale to each file name and use a publishing template to publish to HTML, the links will have the de_DE extension. Is it supposed to work like that so that a Browser can detect the language and choose the correct file if we deliver several languages?
Am I overlooking something?
Any hints are welcome. Thanks and best regards, Tanja
Re: Are there best practices for setting up Oxygen projects in languages other than English?
Posted: Mon Oct 31, 2022 2:24 pm
by alex_jitianu
Hello ,
From what I know, translators are not interested in the names of the files nor do they change it, these are normally left unaffected. I am also unaware of a browser feature that would automatically detect language codes. A translation workflow based on
Fluenta works with a project structure similar with the one described in the
post you've followed. Basically, in the root folder you place content for each language in separated folders (
en-US,
de-DE etc). In the
en-US you have the DITA source documents on which you work. When you are ready to translate to German, for example, you generate an XLIFF file from the
en-US content, send it to translation and when it comes back you generate from it the German content inside the
de-DE folder.
Once you have the content in multiple languages, you will publish them all on your website and it's up to the user to select one language or another. Of course, you could add code that detects the user locale and redirect him to a specific language HTML.
We will soon release a DITA translation add-on based on Fluenta. I will post here the details on how to install it, in case you want to give it a try.
Best regards,
Alex
Re: Are there best practices for setting up Oxygen projects in languages other than English?
Posted: Mon Oct 31, 2022 3:43 pm
by tanja
Hello Alex,
I will look at the Fluenta content you provided - thanks for sharing. I am relieved that my initial setup seems to be okay so far.
It would be great if you could post details on Fluenta when the add-on becomes available. I am looking forward to trying it out.
Thanks and best regards,
Tanja
Re: Are there best practices for setting up Oxygen projects in languages other than English?
Posted: Fri Mar 17, 2023 6:13 pm
by alex_jitianu
Hi,
We have released the
Fluenta DITA Translation add-on which can be installed from
Help->Install new add-ons.... Please give it a try and let us know your thoughts.
Best regards,
Alex Jitianu
Re: Are there best practices for setting up Oxygen projects in languages other than English?
Posted: Tue Jun 20, 2023 9:40 am
by im_rem
Hello,
the Fluenta add-on currently does not handle Oxgen XML inline comments very well. If there is an inline comment, it will split the sentence at the start and end of the comment, so you cannot translate the sentence as a whole (meaning the translation will be faulty, too). This is just as an info for those who use the add-on: it is better to position comments where they will not break sentences.
Kind regards
Re: Are there best practices for setting up Oxygen projects in languages other than English?
Posted: Wed Jun 21, 2023 11:54 am
by im_rem
Hello again,
regarding a different Fluenta addon issue:
To apply different segmentation rules, I exchanged the
default.srx in the following folder:
...\AppData\Roaming\com.oxygenxml\extensions\v24.1\plugins\com.oxygenxml.fluenta.translation\fluenta-dita-translation-addon-3.0.0\configuration\srx
For editing the default.srx, I used the free SRX Editor (by maxprograms) which also provides a function for testing. The test delivered the segmentations I wanted to achieve:
Namely, I want to translate at paragraph level instead of sentence level. That is because there are too many instances where the sentences are split where they "shouldn't be", according to my CAT software, so the CAT software does not even let me save the file I am currently editing --> as a result, I cannot finish the English version of the documentation.
Now, when Fluenta uses the new default.srx, the generated XLIFF still looks identical to the XLIFF it generated with the old default.srx. Did I exchange the wrong file?
I will attach sample screenshots taken from SRX Editor and the generated XLIFF.
Kind regards
Re: Are there best practices for setting up Oxygen projects in languages other than English?
Posted: Thu Jun 29, 2023 5:17 pm
by alex_jitianu
Hi,
Unfortunately we don't have to much experience with Fluenta segmentation rules. I would have expected to work... When we created the add-on, we used the Fluenta API to integrate its actions within Oxygen, but we haven't worked with it extensively. If you have access to a Fluenta desktop installation, it would be interesting to know if the same procedure gives you a different result.
Best regards,
Alex
Re: Are there best practices for setting up Oxygen projects in languages other than English?
Posted: Mon Apr 08, 2024 12:52 pm
by horisonten
Building further on this topic.
What is the best practice for dealing with images/ditavals/custom javascript snippets etc. that are exactly the same between publications (...avoiding duplicates and manual copying)? Say I only use images without text, so all images are the same between the translated versions.
What folder structure do I need to set up so that I can use relative image paths (Webhelp primarily) regardless of the language version of the publication?
I'm trying to find the best workflow for publishing and maintaining a multilingual manual where I want to avoid duplicates of files. Currently I have made exact copies of the Ditamaps and simply replaced the topics with the translated topic counterparts; and then put these copies in separate language folders, for example "en" and "nl", then created a redirect to each copy for each language in my published Webhelp.
But this workflow feels less than optimal since it requires me to copy all images to each language folder, and also the need to maintain separate publications which are identical except for pointing to a different translations of each topic.
Re: Are there best practices for setting up Oxygen projects in languages other than English?
Posted: Mon Apr 08, 2024 9:08 pm
by Radu
Hi,
We have a blog post about translating a project here:
https://blog.oxygenxml.com/topics/trans ... oject.html
In general I think the approach with separate en/fr/de, etc folders would be the correct one, even if you end up duplicating images. Other than that you could have the "images" folder on a higher folder level as a sibling of the en/de/fr/etc folders.
The Oxygen forum is a more static place, most people register to receive notifications only for their posts.
If you want the opinion of other folks in the community maybe you can register and ask around on the DITA Users List:
https://dita-users.groups.io/g/main
Regards,
Radu
Re: Are there best practices for setting up Oxygen projects in languages other than English?
Posted: Tue Apr 09, 2024 7:43 am
by xephon
Hi,
We have a quite complex Fluenta environment and have manuals with 25 languages (mixing rtl and ltr languages). We are not using the Fluenta addon, but integrated a separate Fluenta instance via Oxygen Author actions and Ant scripts. These Ant scripts do things for us, Fluenta does not do. We don't filter any translations, so don't use DITAVAL files with Fluenta intentionally.
Our projects are structured like this:
project
....topics
........en-US
........de-DE
....ditaval
....images
Fluenta imports the XLIFF files to a temporary directory. Then we fix a few things in the DITAMAPs with Apache Ant. First thing is that the temporary directory has to mirror the file structure of your DITA repository. So you need an empty skeleton of directories, because we cannot export directly to the repository, because the translated files contain lots of "en-US" directories, which need to be renamed (at least in our cases). Also, if you have an English DITAMAP with topic references which contain language codes, they need to be fixed. For instance "../topics/en-US/" needs to be changed to "../topics/de-DE/" in the German DITAMAP and so forth. This is the main reason, why we don't use the Oxygen Fluenta addon, because it has no extension points to do something before/after the operations. Afterwards, our scripts correctly integrate the translated topics into the file structure.
We are now thinking about moving Fluenta to a CI server, because it is quite slow for multi language projects. In our cases, a manual has approx. 25 languages and each translated language takes 5 minutes to import. This is a lot of lost working time, when you basically cannot switch Git branches.
Re: Are there best practices for setting up Oxygen projects in languages other than English?
Posted: Tue Apr 09, 2024 3:22 pm
by Radu
Hi Stefan,
You're Just the person I wanted to post on this thread!
Maybe you can consider creating a blog post about your translation procedure and project structure and I will link to it in the Oxygen blog which discusses translations.
Regards,
Radu
Re: Are there best practices for setting up Oxygen projects in languages other than English?
Posted: Wed Apr 10, 2024 11:52 am
by horisonten
xephon wrote: ↑Tue Apr 09, 2024 7:43 am
Hi,
We have a quite complex Fluenta environment and have manuals with 25 languages (mixing rtl and ltr languages). We are not using the Fluenta addon, but integrated a separate Fluenta instance via Oxygen Author actions and Ant scripts. These Ant scripts do things for us, Fluenta does not do. We don't filter any translations, so don't use DITAVAL files with Fluenta intentionally.
Our projects are structured like this:
project
....topics
........en-US
........de-DE
....ditaval
....images
Fluenta imports the XLIFF files to a temporary directory. Then we fix a few things in the DITAMAPs with Apache Ant. First thing is that the temporary directory has to mirror the file structure of your DITA repository. So you need an empty skeleton of directories, because we cannot export directly to the repository, because the translated files contain lots of "en-US" directories, which need to be renamed (at least in our cases). Also, if you have an English DITAMAP with topic references which contain language codes, they need to be fixed. For instance "../topics/en-US/" needs to be changed to "../topics/de-DE/" in the German DITAMAP and so forth. This is the main reason, why we don't use the Oxygen Fluenta addon, because it has no extension points to do something before/after the operations. Afterwards, our scripts correctly integrate the translated topics into the file structure.
We are now thinking about moving Fluenta to a CI server, because it is quite slow for multi language projects. In our cases, a manual has approx. 25 languages and each translated language takes 5 minutes to import. This is a lot of lost working time, when you basically cannot switch Git branches.
Thanks for giving some insight into your translation process. I would be seriously interested in a more detailed explanation of the process, as mentioned and suggested by Radu. I understand if there is no time for you to create an in depth explanation. I really don't know where to start building my own version of your process (with all the customizations needed). So I'll probably need to keep doing it manually until I have more in depth knowledge of what is needed.