search

aframevr / aframe-site

:a: Official A-Frame site.
https://aframe.io/
MIT License
99 stars 141 forks source link

Host internationalized documentation / guides #380

Open ngokevin opened 7 years ago

ngokevin commented 7 years ago

Need to figure this out since besteric on Slack (cn) and taigagaita1 on Twitter (jp) have been translating documentation for respective communities.

Initial thought is to have docs/en, docs/jp, docs/cn in the A-Frame repo.

Questions around how to switch languages. Detect languages? Subdomain (cn.aframe.io)? Dropdown? How to have escape hatches to English in case of outdated/missing docs.

vue.js has cn.vuejs.org, but when it updates, it has to be translated and things go oudated.

cvan commented 7 years ago

Filed #218; can close that one. Would probably be easiest and SEO-friendly to use https://aframe.io/en-US/docs/…

ngokevin commented 7 years ago

Thanks, saw that. I did consider l10n (translating strings hardcoded in the site) vs i18n (hosting translated pages) to be different tasks though. docs/en-US might be easier implementation-wise, does the order in that matter?

cvan commented 7 years ago

docs/en-US might be easier implementation-wise, does the order in that matter?

If the homepage and other non-doc pages intend on being localised, it's probably make sense to namespace all the URLs with the user's locale: /en-US/.

ngokevin commented 7 years ago

Thinking about implementation planning to roll i18n forward:

  1. On A-Frame repository, create a folder in docs/ where translated documentation will live (docs/languages/es, docs/languages/cn). We expose the English documentation on the root level of the docs/ folder so we don't hide it since it will have the most activity. We use only language codes rather than language + country for simplicity.

  2. URL structure would look like https://aframe.io/cn/docs/, https://aframe.io/es/docs/. We'd have to update Hexo scripts to generate the site for each language.

  3. We currently use symlinks pointing to .multidep (node-multidep) to source documentation from the A-Frame repository into the A-Frame site. Figure out what needs to be done here to continue sourcing docs, but with that new URL structure.

  4. Frontend work, route/redirect to the appropriate language of the site, include a dropdown somewhere to switch between languages of the site.

  5. For now, I would only host translated introduction and guides, rather than API documentation (currently, the A-Frame site does not differentiate between the two). The API docs must be as accurate as possible whereas introduction and guides can be more liberal. So for sections such as components or primitives or core, simply show the English version (until/if we split API vs. Guides)

besteric commented 7 years ago

Any process about i18n @ngokevin

cvan commented 7 years ago

I'd recommend using L20n.js, btw.

alexfuser commented 7 years ago

I'm in a group interested in locating A-frame in Spanish. I recommend that you use Pontoon. Which is a product to locate web in an easy way developed by Mozilla.

ArianZargaran commented 7 years ago

Cool!! Alex, good to be in contact. Are you working with @danielowho? Another question was, Are we going to localize Spanish from MX or Latin America and Spain?

alexfuser commented 7 years ago

Hi @ArianZargaran

We are working together with @danielowho .

First we are going to translate it to ES (neutral) and then we make the variants, okay?

ArianZargaran commented 7 years ago

Cool @alexfuser Good to know, since the main object of translating doc files is to "spread A-Frame". Can you share the glossary and the style guide in order to use the same terminology? As soon as you tell me what you guys are working on now, I'll just catch the flow and move to the next doc to translate.