Possibly use GitLocalize to simplify translation work

[chrisvfritz]

As discussed here, translation might be made substantially simpler with the GitLocalize service that @sotayamashita has generously made available to us! 😍 This looks like a great workflow, but I have a few questions/concerns for vuejs.org specifically:

• I notice only .md files are supported. Since we also have other files with localized content (e.g. .ejs), do you think it would soon be possible to support those as well? I'm not sure if it's a deal breaker - it just means some translation work would have to be done outside the service.
• Since we update these docs very frequently and translate to many languages, we currently maintain a separate repository for each language. GitLocalize only seems to support subfolders within the same directory, but I worry that this would create a barrage of pull requests that most people would have to ignore. Are there any plans for multi-repo support?

@kazupon @ChangJoo-Park @gbezyuk @ErickPetru @Jinjiang @ludo237 @haeresis What are your thoughts?

[MachinisteWeb]

This approch is interesting because the basic translation workflow can still be used because at end point, that reverse « PR » to original, and PR from outside are always possible. So this tool is usable in a « progessive » and « incrementaly adoptable » way and it's great!

I just test it, and the tool currently not solve problems we have not already solved only with Github so in our case, that sound like a more « restrictive » process.

• We currently use the number of line to know exactly what can do translated.
• We currently let the translator use the tool of is choice for translate (orthographique help, changes in multiple files, search, .md base for translation (not the actual HTML transformation), etc.).
• We currently use the original repository as « upstream » reference to track what part of file has changed.

For example with vue-ssr-docs, we check « upstream » (https://github.com/vuejs/vue-ssr-docs:master) and merge it into (https://github.com/vuejs-fr/vue-ssr-docs:working). Because we translated french « into » en directory, all new content is noticed by new line, and all modification is noticed by « conflict » (because we have french content). Github tools are now great to solve that.
When work is approved, the en directory from https://github.com/vuejs-fr/vue-ssr-docs:working is reversed into https://github.com/vuejs-fr/vue-ssr-docs:master fr directory.

It more easier with official documentation because we translate directly the good files and we have no « reversed » step to do.

I hope this tool can help team with not already simple translation process and not « restrict » current stable translation process used by others team.

I will notice that to Vuejs-FR tean to have others thoughts :)

UPDATE: Next step to allows us to adopt the tool

• Usage of .md in editable area and not HTML.
• Possible full copy/past outside tool to allows prefered tool to be used.
• Possible edition of others format, even if that is just a usage of plain textarea (for plaintext) or an uploader (for binary).

Great Job @sotayamashita !

[ErickPetru]

I believe all the thoughts exposed by the French translation team are also shared by the Brazilian team. The worklflow of using the original repository as « upstream » reference is also really important for us.

[chrisvfritz]

Just as an assurance, I'm definitely not thinking of pushing translators to use something that won't improve their workflow. 🙂 This is great information so far and I'm glad the newer GitHub tools are making translations easier!

[kazupon]

I notice only .md files are supported. Since we also have other files with localized content (e.g. .ejs), do you think it would soon be possible to support those as well? I'm not sure if it's a deal breaker - it just means some translation work would have to be done outside the service.

In about the above, We use i18n feature of hexo can be exports localized contents to a locale resource files.
https://hexo.io/docs/internationalization.html

we might good to try it once. 😉

[ludo237]

I'm ok with this since I cannot follow the updates of the site very often due to my current job, it's keeping me a bit busy 😢 it would be faster for me to just translate the strings instead.

[ErickPetru]

I'm ok with this since I cannot follow the updates of the site very often due to my current job, it's keeping me a bit busy 😢 it would be faster for me to just translate the strings instead.

It's a good point. A good colaborative tool which allow us to just translate strings would be more productive than trancking and merging changes in many files. I've already collaborated with projects inside Crowdin and Transifex. Just for information, Pagekit translation is there.

[sotayamashita]

@chrisvfritz

I am sorry not to reply fast.

I notice only .md files are supported. Since we also have other files with localized content (e.g. .ejs), do you think it would soon be possible to support those as well?

We will not support .ejs but we think we can extract localized content into config file such as.en.yaml. What do you think?

Since we update these docs very frequently and translate to many languages, we currently maintain a separate repository for each language. GitLocalize only seems to support subfolders within the same directory, but I worry that this would create a barrage of pull requests that most people would have to ignore. Are there any plans for multi-repo support?

We are considering and understand your concern. If we merge other locales into one repository, PR will be getting increasing. However, I think it will not be the problem if there is translation flow. For example, what about to create locale team like Node.js. There are localization teams such as nodejs-ja or node-ko and they will review before merging PRs.

[ChangJoo-Park]

@chrisvfritz Gitlocalize is best option for translate .md. I translated SSR docs with it. 👍
But, Gitlocalize is not working well <code><style></code> syntax 😟 (<style> is eg.)

[chrisvfritz]

@sotayamashita Thanks for this information! It's good to know YAML files would work - I don't think it would be a problem to extract all language content, if we needed to.

Regarding the number of PRs when all translations are a single repo, I agree there are ways we could make it easier and I don't think it would be unmanageable. Honestly, my primary concern is a little selfish: for myself and others who watch this repository and so receive notifications on every issue/PR, it would be a little frustrating having to ignore most notifications. 😅 It's a shame GitHub doesn't have more refined notification options, allowing me to ignore anything with a specific label, for example.

[kazupon]

I could export locals of .ejs as .yml file.

See the commit:
kazupon@fad4782

I put the src/languages directory it.
I think we need to configure source_dir option (e.g. src/ja) of _config.yml, in order to translate with using GitLocalize.
At that time, Also we need to move new directory (e.g. src/en) from current managed source files (src/**).

When we check or deploy translated documentation, need to set language option of _config.yml to target language (e.g. ja).

[chrisvfritz]

@kazupon I love it! I think since we're still undecided on whether GitLocalize would be feasible, maybe it would be good to change the en language to just current? That way, all layout files could be quickly translated in a single file, which would be an improvement even for our current workflow.

Later, if we decide to manage all translation work in the main repo, we can change it back to en and add new languages.

What do you think?

[kazupon]

maybe it would be good to change the en language to just current?

yes!, for the japanese (jp.vuejs.org), japanse translation team translate in src/languages/ja.yml, and need to change to ja language.

Later, if we decide to manage all translation work in the main repo, we can change it back to en and add new languages.

In about the above, we can be specified multiple languags with language options like the below.

language:
- en
- zh-tw
- ja
- ko
- ru

[ludo237]

Do not forget Italian, I'm in with this idea and I will work for the IT file

[chrisvfritz]

@kazupon Forgive me if I have misunderstood, but what I was actually thinking is to have only one language called current (and it could have the same name in translation forks, as it would always refer to the current language in that repo).

This way, we would have all language content from layout pages organized into that single YAML file, but translators can still manage all work in their own repos.

Does that make sense? Would this work well for translators?

[kazupon]

@ludo237
sorry, the above example was bad ... 🙇
I don't forget Italian vue users 😺

@chrisvfritz
sorry, my poor english ... 🙇

Yes! I think so.
Hexo can localize with current language (language: en in _config.yml) from src / languages / current.yml.
In that way, translators can manage all work in their own repos with not using GitLozalize.

[chrisvfritz]

I think it's clear GitLocalize doesn't fit into our ideal workflow (yet), so closing this for now. Happy to reopen later if anything changes. 🙂