Localization

[yccheok]

As, this site info is helpful for non English speaker. It is good if translator can participate to translate this site as well.

I can contribute to translate the info to simplified Chinese and traditional Chinese. I think the major obstacle is that, I don't know how to translate UI text, for respective device. (Unless we have access to those device)

[Artaud]

Don't want to sound rude, but wouldn't Google Translate be enough? Just as you say, the major issue is that we don't have access to those devices and frankly, I assume the site will be updated often and translations would always be lagging behind.

[yccheok]

Yes. I know the issue, and me neither have any solution.

Regarding Google Translate, its quality is still hardly on-par with human translator. I use it as a tool to help me quickly understand a foreign language article. But, if I want to produce some content for end users (For instance, producing text for Google Play store description, text used in screenshots, text in Android app), I will ask help from human. I can hardly happy with the quality from Google Translate.

[ol-v-er]

English should be enough for Android developers and advanced users. However, if the maintainer accept this issue, I can do it in french.
Maintaining the translation will be an issue...

[alamos-gmbh]

Implemented the API, already got contacted by a user if this information was available in German.
I'd be happy to provide German translations if it becomes possible to include translations.
Should be separate files, though, otherwise the API response become too big. (URL parameter, maybe?)

I think the user_solution part would be enough, the rest can remain English.

Also contacted you via email with the same information.

[Artaud]

Hi everyone, I'm sorry but I'll close this issue as I think it really really unrealistic to ever maintain any translation. This project is probably not going to freeze anytime soon so translation is a sisyfic job...

[Trumeet]

Any considerations now? This project is really helpful for Chinese developers, who have the major audience of Chinese vendors.

[Artaud]

The main issue is still keeping any changes in sync after a change in the source language. So - I'm trying to think of a solution here....
I'm still strongly opposed against manual translations.
For visitors of the site, if they use Chrome, they can get a translated version easily. However adding a Google Translate icon to the top bar might be a good idea?

More important issue is translating the API. I'm thinking we could set up a CI task that would take the JSON files that the API serves and run them through Google Translate again. What do you think about that?
Would you be able to do that @thubalek for example?

[Trumeet]

The main issue is still keeping any changes in sync after a change in the source language. So - I'm trying to think of a solution here....
I'm still strongly opposed against manual translations.
For visitors of the site, if they use Chrome, they can get a translated version easily. However adding a Google Translate icon to the top bar might be a good idea?

More important issue is translating the API. I'm thinking we could set up a CI task that would take the JSON files that the API serves and run them through Google Translate again. What do you think about that?
Would you be able to do that @thubalek for example?

Using Google translate may not be a good idea for some situations, for example:

• User are not using Chrome (Most Chinese users may not be using Android Chrome on their phones)
• Google Translate in Chrome are blocked due to censorship (Google translate is available in China, but I'm not sure if the Chrome translate is available)
• User may be too stupid to click on translate. (lol)
• My app is planning to use https://github.com/doubledotlabs/doki or similiar solutions, which uses API and displays content natively rather than opening a browser.

[thubalek]

If make an agreement I can implement it. Later today I'll look at the API.

[Artaud]

Right, so let's start with translating the API.
What we need to achieve is having the current files that reside at /api/v2/[vendor].json appear translated at /api/v2/[lang_code]/[vendor].json

After a quick look I can see a few caveats in achieving this regarding how the project is currently set up.

1. The v2 API json files are generated on build by Github Pages engine, meaning we don't have access to the final JSON in commit time.
2. The JSON files are generated through the _layouts/api.json template, as a Jekyll collection (defined in _config.yml). A simple way to get translations would be to declare a new collection for each language, and throw together a custom Liquid translate filter that would use the Google Translate API to output the JSON translated. However on Github Pages we cannot use custom plugins. So this could be only achieved if we opted out of Github Pages build engine and build the pages through our own CI solution (and mind me, that would be really great for other reasons as well).

I'm definitely open to other ideas...

[fennifith]

I'm opposed to automating the translations of this material as it will have a noticeable effect on the quality and usability of the resulting text, and could change the meaning unintentionally; Google Translate is not often used for translating technical/software instructions.

As for maintenance, I'd like to point out that I, a sole developer and full-time college student, maintain multiple localized translations (the values-<locale>/ dirs) in nearly all of my Android apps. Granted, I rely almost entirely on pull requests to keep them up to date, but it is not overly difficult to keep track of - though I have been taking a bit of a reprieve as of late to focus on classes. They might not be of the same influence or scope, but they are definitely significant in quantity - and I think the influence of this repository functions as an argument for creating translations, if anything. Regardless of whether they are entirely up to date, having any translations at all is better than nothing. There are people offering to donate their time to make this project useful to other people, and on principle I don't like turning those contributions away.

Sorry for the mini-rant. Back to technicalities: A workflow here could be as simple as creating an issue whenever a change is made to the original file, and tracking its progress until it eventually propagates to all of its translated versions. (maybe writing an issue template with all of the locales listed as check boxes could make this easier?)

---

As for the viability of implementing this on the current Jekyll structure - looking at this blog post as an example, it definitely seems possible to achieve this without using a custom plugin, and that would make it open to manual contributions as well. Here is what I would propose changing:

• create subfolders in the _vendors collection for each locale (solely for organization - doesn't affect how Jekyll treats them internally)
• assign a ref: <vendor> and lang: <locale> attribute in each file as detailed in the blog post
• add a categories: [ '<locale>' ] to each translated locale (this will make more sense in the next point)
• change the permalink setting in _config.yml to :categories/:title (there's a fairly restricted list of variables that can be used in permalinks, but I believe this will work)

This should create the translated files in, for example, /zh/huawei, while leaving the untranslated files in the same place. The one caveat is that the same will have to apply to the API; the en locale will be an exception to the .../<lang>/<vendor>.json pattern, and will appear at .../<vendor>.json instead. This has a good side, though, as it means the current files will stay in the same place, so any projects currently implementing the API will not need to make any changes.

I am definitely willing to create a PR to implement this, with approval.

[fqborges]

@fennifith thought I do not fully understand the details, it seems to be a good solution. I am just wondering how much work would be needed to keep translations in sync.

For example, I used to translate contents for a game using gettext, that maps the original strings to the translated strings, making easy to track changes, updates needed and completion. Having this would be a must, for community driven translation.

[thubalek]

There is definitely problem if sync if translation manual. If you change original text then you have to notify translator for all languages and make sure they translated text.

I'm afraid this will be hard to implement just using GitHub infrastructure. This is usually implemented in translation web apps like https://www.oneskyapp.com/, https://crowdin.com/ or https://phrase.com/

[fennifith]

@thubalek

There is definitely problem if sync if translation manual. If you change original text then you have to notify translator for all languages and make sure they translated text.

I don't entirely see why this is a problem; assuming all contributions are looked over before being merged, all you should need to do is check the last modified date of the translated files to see if they're out of date. I don't see why it's necessary to explicitly notify translators of a change - if someone has made a contribution, they shouldn't be expected to maintain their work indefinitely. Any other contributor could easily take over and help keep them up to date. Opening an issue as soon as the translations are made out of date should make it possible to publicly track which sections of the site need translating (thus the suggestion of an issue template). Perhaps assigning a label could make it easier for contributors to filter these issues from the rest? You could even automate this process with a git hook or github actions if you really see the need.

If there is really a need to use a web app for this, I've heard of success with using OneSky, but I don't see how proxying contributions through a third-party interface could possibly reduce the amount of maintenance work compared to accepting contributions directly into the repository.

[thubalek]

Lets imagine scenario when we have document for Nokia. We have volunteer that will translate it from English into (e.g.) Catalan. Everything is fine.

Then we update that document adding new section. Our volunteer is no longer available and there is no other volunteer for this language.

What we will do? Will we stay outdated for Catalan? Will we remove Catalan translation until some other volunteer submits update?

I have many years experience with I18N of my apps and it is always very difficult to find volunteers for exotic languages and keep those translations up to date with default translation. Most of those translations ends in half translated state which does not look good.

And maintenance of android translations is easier as strings are mostly one or two sentences and you can compare current original with original from the time of translation. It is even harder to track changes for free form translations.

To overcome this issue it is necessary to have automated system of begging for help as you can have easily 15 or 20 translations to maintain (I have 32 languages for Battery Widget Reborn, between 10 and 20 for my other apps)

[Artaud]

Thanks a lot for the discussion.

I agree with @thubalek that maintenance of translations is very hard and would need a very dedicated manager around. I believe that while we all appreciate the impact of DKMA, there's no one here who could dedicate a significant portion of his time to it.

I also agree that machine translated texts are a poor man's solution. At the same time, I don't want to turn away people who actually offered their time to the translation.
We were thinking about this a little more and @petrnalevka came up with two different possible solutions.

1. Forking the repo
   For each translation, the translator could fork this whole repository and set up a new Github Page with the fork. From the main site, we would redirect a subdomain (e.g. de.dontkillmyapp.com) to this fork.
   All translators for the given language would then gather around that fork.

This way has multiple pros:

• all text would be kept in English until translated
• we will have a simple way to switch languages out of box in both API and frontend
• a transparent way of publishing translated texts to API consumers such as Doki
• translators would have dedicated Github Issues space to discuss specific translation

Keeping the site in sync with the upstream DKMA would mean just doing a git pull once in a while.

2. Using GitLocalize
   I just found this tool that not only serves as a web translation framework but works directly on top of Github and seems to be able to track changes in the source language (English) and compare them to the translation. Thus showing the parts that need translation.
   It will create a new folder for each language, so that will also take care of the JSON API files generation.
   Seems to be the tool for the job, whaddaya think?

[Artaud]

Anybody voting for GitLocalize? To me it sounds really cool, simpler and more powerful than everything that we came up with before.

[ubuntudroid]

What about weblate? Never used it with a web project, but in our company we have a very well working setup for our mobile apps. You can also easily keep it in sync with your repository, just as GitLocalize, and they have a polished UI for doing translations. They have outstanding support and it is free for open source projects. I'm not affiliated with them, just a very happy user. ;)

On a related note: I can help with German translation.

[Artaud]

@ubuntudroid I've chosen GitLocalize. It doesn't have as polished interface but it is a lot easier to setup and it seems to me that Weblate is really well suited for short strings, whereas what we have is a big chunk of text that's hard to break up.
I'm going to setup GitLocalize now and invite all the people who offered to help with translations.

[Artaud]

@ubuntudroid @yccheok @ol-v-er @alamos-gmbh @Trumeet
To everyone who offered to help with translations:

I have set up GitLocalize for this repo. If you still want to help with the translation, please sign in to GitLocalize at https://gitlocalize.com/ and let me know either here or at [email protected] - I'll add you to the project.

How to translate:
At https://gitlocalize.com/repo/3613 you can see a list of languages. If your language is missing, let me know and I'll add it (not sure what access level is needed for that).

Tapping on the language takes you to a file picker. Go to _vendors folder, then select the *.md file you want to translate. Tapping on it takes you to an editor.
In the right column, you'll see several fields.
What we want to translate is explanation, user_solution and developer_solution. (They don't all have to be there).
Please don't touch the other fields.

After the translation, click on "Create review request" and I'll review it and merge into the repo.

Thanks a lot for everyone involved in the discussion and especially to any potential translators!

[EstebanForge]

@Artaud thanks :)

Just registered at GitLocalize. Can help with Spanish here. Same username as here.

[Artaud]

@TCattd Perfect, thank you! I've added you to the project.

[fqborges]

@Artaud Thanks!

Please add me @fqborges, lang: pt-br (Portuguese (Brazil))

[Artaud]

Added @fqborges !

[rzetzsche]

I would be happy to help with a translation to German. @Artaud

[KovalevArtem]

I suggest using the Weblate platform too. It's completely free for open source projects.
I will be happy to help with translation into Russian.

[lreyn]

Hi @Artaud - could you add:

• @LuisAlfredo96
• @lreyn

we can help with the Spanish translations as well.

[mlscherer]

Hi, please add be as pt-br - Portuguese (Brazil) contributor

@mlscherer

[rzetzsche]

@Artaud Is this still something you want to have? It looks pretty stale but I think it is a pretty useful enhancement. I would love to translate some parts of the website.

[golshani-mhd]

Great work @Artaud,
I would be happy to be the translator of the Persian language (language-code: 'fa-IR' or 'fa').
Please add me @golshani-mhd too.

[mantaroh]

Hi @Artaud

Could you please add @mantaroh ?
I'd like to add the Japanese (ja-jp) translation.

[and3rson]

@Artaud I'm willing to help with Ukrainian translation. Same username as here (@and3rson).
Thanks in advance!

P.S. Is the main page translatable as well?