HOW-TO: Translating OJS and OCS

[jmacgreg]

Expanded documentation on translating OJS and OCS is now available:

* http://pkp.sfu.ca/files/docs/translating/index.html (HTML)
* http://pkp.sfu.ca/files/docs/translatin ... lating.pdf (PDF)


The Table of Contents is as follows:

Preface
Introduction
Checking Language Availability
- Checking Your Software for Available Languages
- Checking the PKP Website for Available Languages
Installing a Language
Translating OJS and OCS
- Creating a Manual Translation
- Using the Translation Plugin Tool

[Ojser]

Hi,

I'm sorry to post under an old post but here it is the most relevant place for my question.
- I just would like to know how "long" would take the translation of OJS to another language ? Is it at order of hours, days, weeks..?
(of course, it depends on time devoted but I'm asking in average for somebody who isn't developer?
- By the way, should we be developer to translate OJS or we can do it "without deep development knowledge"?
- And finally, which files that should be translated?

Thank you very much for your feedback

[ramon]

Hello Ojser,

If you're talking about translating the interface, it can take anything from 2-3 weeks to 6 months, depending on your skills, tools used, time constraints, availability.

The easiest way for anyone to translate OxS is to enable and use the Translator Plugin available. It will help you check and create the files as you go.
However, it is not as fast for someone with a more powerful XML editing tool, and is quite error prone, as you may hit the "enter" key inadvertently and save a file without concluding your work. This is most annoying when editing the translation on the form resulting of a translation "Check" or when you create a new file and it has loaded the default content. Finding the variables is boring, to put it plainly.

The translation doesn't have to be done all at once, anyway, mainly because of the sheer amount of files.

As I longtime OxS translator, I tend to use the Translator Plugin to check new variables and files, while editing them with VIM.
VIM is a very powerful text editor. I recommend it because it's easy to set the charset to UTF-8, edit multiple files at once, execute regex to edit multiple values at once. It takes a while to get used to, learning the copying-and-pasting, deleting, but the ability to edit multiple files at once is exceptional, as you can use variables from different files and compare files to check your work.

A good way to start is to edit the smaller files first. It will seem as you've accomplished and finished a lot more than editing very long files. However, some of them may not seem important at first and the translation will appear incomplete for a long while.

Also, the PKP Team used to release a translation installation for OxS translators, so we can keep translations updated, but this hasn't happened in a while.

_______________________________
Ramón Martins Sodoma da Fonseca
Analista em C&T
Coordenação de Tecnologias de Informação
Instituto Brasileiro de Informação em Ciência e Tecnologia - IBICT
Ministério da Ciência e Tecnologia - MCT

[Ojser]

Thank you very much for this answer.
Yeah, I'm talking about interface translation .
If I enable Translator plugin and use a language already included in OJS as my translation template, will this be a right choice?
To be more practical, let's say, I click on "Translate", I choose English or Portugal as my template to translate ojs sections to, say Hebraic, then I click on "Edit" and start translation, will this be working?
If so, how to save the translated data to the new language, not as an edited version of the template being used but as a new language?
Am I approaching the question from a wrong side or it is a right way?

Thank you a lot

[ramon]

Hello Ojser,

I would use the default English locale as the template (that's the one the Translator Plugin uses), simply because it's always the most complete one.

I think this document will help you decide which path to take and how to proceed with more completeness than whatever I write here.
_______________________________
Ramón Martins Sodoma da Fonseca
Analista em C&T
Coordenação de Tecnologias de Informação
Instituto Brasileiro de Informação em Ciência e Tecnologia - IBICT
Ministério da Ciência e Tecnologia - MCT

[Ojser]

Thank you ramon.
When I cited Portugal, it was just an example. Given OJS is written in English, this inevitably makes English as the template.
Thank you for the link. I'll read it and come back if I'll still have questions.

Regards,

[ramon]

Hello all,

I just came across an interesting site: Transifex
I'm not sure it works with OxS locale files, but could be tested.
Anyone volunteers?
Would you guys like me to make an attempt and report my findings?

It seems it can also be downloaded and installed somewhere else.

The only caveat is that, at least as a translator, I can't edit multiple files at once.
This is the only issue when translating software, because you need to remember how you translated a string or block of text that is used or referenced somewhere else.

PS: Again, if OxS could add the ability to use variables within the locale files, that would be a great advantage. There would be a need to take into consideration special language issues, like term ordering and so on, but it can be done.

[Ojser]

Hi Ramon,

May I ask what "advantages" this site might offer over the translator plugin?
Having took a quick look at transifex, I didn't know how it works, whether as an online form or with automatic translator tool
The only think I understood is: it is limited to 15000 word, beyond it is paying!
How many words in OJS? and how words are counted (is "a" a word? )
I've already started to use the translator plugin but I feel I'll abandon!
It seems so long with already some errors: multiple sign (#) surrounding the texts, the locale file (locale.xml) is still empty...etc!
So, I stopped for now...

[ramon]

Hello Ojser,

Please do not give up just yet!
Translation of OxS software IS A DAUNTING task and seems to take forever.
I was just thinking Transifex could make the translation easier somehow, but I'm just getting to know it. I wasn't aware of that limitation, although I worked on a shared project that had a lot of files without problems.
It has online editing and language comparison, collaboration with check-in (notifying users of a filed being worked on with a lock icon), some stats on completion, but my tests indicate it doesn't work well with OxS XML languages files.
It may need some custom code to work properly as it is not a "standard" translation file. It's a plain XML file.
It does load the files, but it mixes up the variables, not sure why.

Again, OxS translation process is not an easy task, and, based on the OJS structure, not an easy thing to change. This is something OxS needs to improve, although I can tell you from experience, that software translation is really a pain... and maintenance will depend on your involvement and time available.
Once the main translation is complete, though, maintenance tends to be easier with the Translation Plugin.
Translation also helps to understand the theoretical inner workings of any software without actually testing it.

Attached you'll find all the original English language files

en_US.tar.gz

OJS-2.3.7 original English files

(390.95 KiB) Downloaded 58 times

.
Use WinRAR to decompress, as WinZip tends to remove empty folders, although I don't think there won't be any.

Use a simple text editor that can save as UTF-8.
I like VIM for editing translation files, especially on the server side as I can run other command-line tools such as GREP, edit multiple files at once that have a specific variable or function call and compare files.
BUT, you can use any you feel comfortable with (Notepad++, PSPad, even Wordpad may help...).

Change any en_US calls to your desired language, according to ISO language codes (including comments and folder name).
Once you're done, add the files to a clean OJS install, with the language registry modified to include your language.
Remember to reload the language when you make significant changes to it and clear data caches frequently (keep a tab open for this).

When you find ##key.name##, or something similar, it just means the variable is not translated.
Using vim `fgrep -l key.name \`find . -name \*.xml\`` (on a linux server, at OJS's root level) will open all XML files with that variable in it.
After saving the changes, refresh the page and it should display the correct translation.
If not, then there may be other things at play.

When completed, compress everything to a Zip or Rar file and mail it to PKP's Team.
They'll add the language to the language list.

[Ojser]

Hi Ramon,

Sorry to come back so late. I was involved in the translation but I'm a little bit frustrated now! I was almost about to finish using the "check" option in from the translator plugin but nothing was saved!
When I clicked on "check" and translated all missing data, then I "saved" but non of the data I provided was saved!
Do you know why this issue? Why "save" doesn't save data when used via "check" option?
I lost hours and hours of works! It's crazy and frustrating!

[ramon]

Hello Ojser,

I'm sorry to hear this!
It has happened to me before and it tends to be because of permissions in the locale folders.
However, you don't have to translate everything at once in that "check" form.
You can save regularly so you don't have timeout problems and test if it's saving.
Sorry I forgot to mention this...
It's been so long I've worked in the translation I forgot the details that wreak havoc on our work and test our patience...

Set the ojs2/locale/ plugins (there are locale files for each also), as well as ojs2/lib/pkp/locale to 775 or 755 (whichever works in your setup).

If you have access to your server and it's Linux based, I would suggest you create an english locale package.
The one I provided on my previous post should get you started.
The "manual" translation process may be easier for you...

Download and decompress that in your local computer, then create your language structure by copying the English one and renaming the folders to the appropriate ISO language code (I don't know what that is for Esperanto!), within each locale folder.

Then, use VIM (there is a VIM for Windows, just search for that on the Web!) to open the English file you want and the Esperanto one, with Vim's VIMDIFF feature.
Make sure you use "set: charset utf-8" to save your files as UTF-8 encoding.

The only one you won't have there is the translation for TinyMCE, which you'll have to search in Moxicode for.
There's an Esperanto download available on their language page.
Select your language and click the download button at the end. This package needs to be decompressed and sent to your server (FTP), in ojs2/lib/javascript/tinymce/ or something like that.

I'm working with the PKP team to find a better solution for translating PKP software... but we haven't found one yet...

[Ojser]

Thank you very much, Ramon.
It is a little bit painful to lose work after hours and hours of concentration and effort!
I've already checked my folders and files' permissions, and they are set up at 755 (for folders) and 644 (for files). The write permission is also selected for the user (for me!), so I don't know why the writing and modification I make are not kept!
I've also downloaded Vim (upon your recommendation) but I feel it is less powerful than Notepad++, isn't it? (unless I miss the right version or any special configuration, if any)!
Actually, it has a "basic" interface with few options compared to Notepad++; it looks like the Microsoft notepad, while Notepad++ is much more featured!
The curious thing with Notepad++ is that OJS files appear encoded as (ANSI as UT-8) rather than UT-8!
So I don't now if I should to register them unambiguously in UT-8 encoding.
I also downloaded the file package you provided in the post above and I'm working on.
But, I think there is an advantage of the Translator Plugin over the manual translation, that is we have the source language always available above the target one, so we always have an eye on the source! We, then, don't need to open 2 windows to refer to the English version. But you are completely right, it is safer to use the manual option to avoid losing data, like what happened to me! Also, an "huge" advantage of Notepad++ is that it allows to make Undeo/Redo operations up to many many times backward/forward! This is very practical when making errors.
[The iso code for esperanto is (eo, epo)].

[ramon]

Hello Ojser,

I don't know Notepad++ that well, so I can't compare.
Although Vim may seem clunky and old-fashioned, you can use many special tools.
It's actually difficult to keep up with all of them.

If Notepad++ can change the settings to UTF-8, I would recommend that!
That may have been caused by FTP transfer configurations, operating system's way of recognizing files, besides Notepad++.
That happens quite often, in most Windows based environments.

Vim has the Vimdiff tool which allows you to open 2 or more files for comparison side by side.
Use CTRL-w to switch between "tabs", INSERT or I or A to start editing. To undo, press ESC then the key "u". It will undo quite a bit.
You can use regular expressions to replace text.
For searching, press ESC to exit whatever state you're in, then forward-slash "/" then type the word you're looking for...
To save, press ESC, then colon ":" then w to write (save), x to write and exit, or q to exit without saving changes.

I used to combine the editing tool with VIMDIFF, so I could edit the file, then reload it in VIMDIFF to keep comparing.
That's another way of working, but, after I learned a few Vim's commands (like copying multiple lines, navigating jumping words, searching and the regular expressions) I tend to use it more often than not.

Anyway, you should work the way you feel more comfortable with.
Good luck, and hope this time you'll get it done more quickly and with less problems.

[Ojser]

Thank you Ramon.
I also hope get it with the less problem possible!
You should try Notepad++, it is a free powerful tool! I think it is largely used by a large number of developers.
By the way, do you know where are the months names, in which file?
Curiously, I have the month names translated but not properly! Most of them are correctly translated but still some errors to be corrected. I don't remember if it was me who translated them (and I don't remember in which file I found them!) or they have been translated automatically!
I searched in many files (locale.xml and other files; common, admin...etc.,) but I don't find them! Where are they?
By the way again, is there a way to list the content of all files in one place/file and look up for any desired term, for any potential correction or re-translation?
I tried to convert XML files into one single PDF file to easily lookup in but they seem not to be convertible!
The "Check" option in the translator plugin would have been a good way if it shows the content of all files, but unfortunately it doesn't! It only shows the items that need translation, not all the file contents!
This is a drawback!

Regards,

[ramon]

Hello Ojser,

I think the month, date format and some other basic language attributes are actually set by PHP's locale() function.
And those may be incorrectly translated, but it's beyond me to know where or how to fix that.

I don't think Notepad++ will enable you to do a full search on all files within a folder or project (not sure it has that "project" feature), or edit multiple files at once AND compare them.
For this, you can:

• Use your operating system do do so, running a search for the term within the select files, folders or file types.
• Use an IDE that has search capabilities in XML files (Dreamweaver and phpDesigner are paid, RJ TextEd is free, but they enable you to create projects and search within files and folders)
• If you are hosting your system in a Linux box, and have SSH access, you can use grep in the command-line to search within a folder, like so: grep -i "MyText" * (the -i for case insensitive search; if you want further down the folders, just add */*, so it's grep -i "MyText" */*, and so on). And you can use other tools as well. It will show you the file name and where it found the text you searched.
• If you open GVIM on Windows you will have a graphical interface for opening files and comparing them side by side. Useful when you know that multiple files use the same text, or you want to keep track of some terms and phrases already translated for reuse. You can then use the forward slash (" / ") to search one file at a time for content. On Linux, you can run vim `fgrep -l MY_CONSTANT_OR_FUNCTION_NAME \`find . -name \*.xml\``. Alec Smecher sent me this, and what it does is open all files that have the variable you search for editing. You will then have to edit, then save and move to the next tab/file.

Yes, the Translation Plugin has that drawback if you already have made a translation and saved it.
Except for the "check" tool, it only edits one file at a time and its search only works for full translation keys, not values.

_______________________________
Ramón Martins Sodoma da Fonseca
Analista em C&T
Coordenação de Tecnologias de Informação
Instituto Brasileiro de Informação em Ciência e Tecnologia - IBICT
Ministério da Ciência e Tecnologia - MCT