Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] Docs i18n #4633

Closed
wants to merge 14 commits into from
Closed

[WIP] Docs i18n #4633

wants to merge 14 commits into from

Conversation

zpao
Copy link
Member

@zpao zpao commented Aug 15, 2015

We went past the tipping point on this a while ago and we need to surface our translated docs. I spent some time this week looking into other options for generating our site but this gets us there way faster with minimal changes. It's only half the work though - there but there's still a bunch to do. The infra is here now but we're still going to have some hacks we have to do to make links work right.

How it works (we're using http://jekyll-langs.liaohuqiu.net/):

  • translated files live side by side like we already have with the exact same file naming convention (though perhaps we will end
  • translated phrases live as key-value pairs in _i18n/lang.yml. I've done as much of the Korean as I can (copy + paste from the titles in the docs files)
  • We can use these keys in a lot of places, {% t string|key %} outputs the value and will fall back to English (default).
  • Due to limitations in how Jekyll passes things around there unfortunately a lot of duplicate keys in these files. I tried to cut it but couldn't make it work.
  • English is unchanged (well except for 1 tiny thing which actually is broken on 1 page)

Give it a try:

I set up a testing server - http://reacti18n.zpao.com/react/ko-KR/docs/getting-started.html

Links are definitely broken right now so no need to remind me :)

But I wanted to get some feedback before I took it any further, namely from the people who have been doing the bulk of the translation work - @tako-black, @makky3939, @marocchino, @sairion (and many others, perhaps you can spread the word amongst the translators you've been working with?), @spicyj . Does this approach so far seem like it's more maintainable for you moving forward? All of your current links will be broken but I'm not too worried about that (are you?).

TODO:

  • make next / prev / sidebar links actually go to current language. Might need to do full paths in next/prev, needs more investigation
  • link to other language entry points somewhere
  • decide if we want full locale in the url or the short version (/ko-KR/ vs /ko/, /ja-JP/ vs /ja/, /zh-CN/ vs /zh/ (or cn?))
  • Make header fragment links work
  • language specific CSS (eg, font-size)

@kohei-takata
Copy link
Contributor

@zpao
Thank you for your changing!
I saw the testing server and I think it looks good.
I think the way of translating will not so be changed except the links and titles, and modifing links is not so hard for me.
So I'm not worried about this change.
I think short version (like /ja/) is simple and better.

Tell me if there are what I can do for this change.
Thanks!

@makky3939
Copy link
Contributor

@zpao
Thank you for your activities.

I checked the testing server. I think it looks good.
I think the short URL is good because it's simple.

Please tell me if there is I can do.
Thanks!

@sairion
Copy link

sairion commented Aug 16, 2015

Seems great, thanks @zpao ! Been waiting for this. Many Korean users (as far as I have seen) are still reading English docs, even though full translation is available in Korean. I usually give people URL of our separate docs website (http://reactkr.github.io/react/docs/getting-started.html)

It would be also great if this approach can be applied to other libs like Relay, Flux, React Native, whatever lib React developers usually gets into. If enough consensus is made, React-KR contributors may be able do the same i18n job for other libs' websites.

Regarding the localization url, most of the people whom participated in the translation project agreed using 'ko', instead of 'ko-KR'. Not entirely sure North Korean or Korean-Chinese people agrees that. ;) /cc @marocchino @dittos @arkist @dalinaum

Not mentioning it needs to be done right now, but one more feature request is language-specific CSS. The docs website does not really look good when it is written in Korean (line-height a bit too low for Hangul characters, font can be replaced to better one, etc.)

Thanks, and please tell us if there's anything needed. 👍

@zpao
Copy link
Member Author

zpao commented Aug 17, 2015

Thanks for the feedback, I think we'll move forward with this and get it into shape for 0.14 launch (if not before). And it sounds like the general consensus is to use the short urls. I'm not sure how many North Koreans are using the site but they'll have to survive for a bit longer ;) We can always move to a longer url if we need.

There's nothing for you all to do just yet, but stay tuned here - we'll have a little bit to do soon.

It would be also great if this approach can be applied to other libs like Relay, Flux, React Native, whatever lib React developers usually gets into.

I'm hoping we land on something that can at least conceptually be shared. Right now we're using a different site generator than those projects. I'd like us to converge on a shared stack soon so that we can solve these things once but we haven't yet.

The docs website does not really look good when it is written in Korean

Ah, I hadn't even thought about that! Thanks, will definitely see what we can do about that.

@sairion
Copy link

sairion commented Aug 31, 2015

While reading through docs, I found one more thing needs to be done: fixing broken fragment identifiers. Example: http://reacti18n.zpao.com/react/ko-KR/docs/getting-started.html If you click on subheaders, you will see it does not work and most of non-ascii characters got cut out.

@zpao
Copy link
Member Author

zpao commented Aug 31, 2015

@sairion Good catch. I'll see what we can do about that.

@marocchino
Copy link
Contributor

@zpao How is it going? Should I update translation or wait for this PR? 😐

@zpao
Copy link
Member Author

zpao commented Sep 15, 2015

Sorry, no update here yet. I'll try to come back to it later this week. Feel free to update translations in the meantime!

@zpao zpao mentioned this pull request Sep 22, 2015
@facebook-github-bot
Copy link

@zpao updated the pull request.

@zpao
Copy link
Member Author

zpao commented Nov 14, 2015

Came back to this for a little bit tonight - luckily rebasing was pretty painless since I'm mostly just touching the metadata. Sidebar links and next / prev work and stay within the language you're already on.

@joecritch
Copy link
Contributor

@zpao Anything I can help with? Typography, language links, etc? I stumbled across this after feeling your pain of updating prev/next links 👍

@gaearon
Copy link
Collaborator

gaearon commented Mar 26, 2016

It seems likely that we’ll revamp the docs completely in the coming months so maybe this isn’t worth the effort at this point. I’ll leave it open though.

@zpao
Copy link
Member Author

zpao commented Mar 28, 2016

Nothing actionable at this point. I'm still considering options that aren't Jekyll to make this better. I also want to get an external service setup with will help translators know what needs to be translated - the situation we're in with partial translations and not picking up updates to content consistently is rough.

I'll leave it open because I think what I've spent time on is valuable at least as a reference for whatever happens next, and it's good for people to know it's (at least sort of) being worked on.

@sophiebits
Copy link
Collaborator

@gaearon Can you say more about which revamp you mean? I know @joecritch is interested in helping out with docs updates.

@gaearon
Copy link
Collaborator

gaearon commented Apr 15, 2016

I was referring to one of the weekly meetings but maybe I got it wrong. I thought at some point I heard that the existing docs were not written very cohesively, and somebody (from the Parse team?) might eventually help us write some of them from scratch.

@zpao
Copy link
Member Author

zpao commented Apr 19, 2016

FWIW, there's nothing set in stone in regards to a content revamp, just some general hopes that it'll happen.

@koba04
Copy link
Contributor

koba04 commented Oct 13, 2016

Do you have any plan for to translate New Docs? #7864

@gaearon
Copy link
Collaborator

gaearon commented Oct 13, 2016

@lacker What's the plan about this?

@lacker
Copy link
Contributor

lacker commented Oct 13, 2016

@thejameskyle is building an open-source-docs-translations-pipeline thingy for Yarn and we were hoping to reuse some of it for the React docs. @ericnakagawa and I will sync up with him when he's back in CA

@koba04
Copy link
Contributor

koba04 commented Oct 14, 2016

@lacker That's so awesome!
Please let me know if you need any help.

@gaearon
Copy link
Collaborator

gaearon commented Oct 23, 2016

I'm closing as too outdated.
Let's continue the discussion in #8063.

@gaearon gaearon closed this Oct 23, 2016
@gaearon
Copy link
Collaborator

gaearon commented Feb 25, 2019

We've launched our first translations, and many need more contributors.

https://reactjs.org/blog/2019/02/23/is-react-translated-yet.html

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.