zh-TW: Day 1 Translations

[henrif75]

Professional translations for missing day 1 entries #684

The diff is large mostly because of the normalization.

[victorhsieh]

Wow, the diff is 21K lines. Any hints to help me narrow down to smaller ranges?

[mgeisler]

The diff is large mostly because of the normalization.

What kind of normalization are you doing?

My guess is that you've used mdbook-i18n-normalize? You don't have to do this since there hasn't been any non-compatible changes made to mdbook-i18n-helpers since version 0.2.0. Infact, mdbook-i18n-normalize is a bit clumsy: even with google/mdbook-i18n-helpers#93, there will be differences in how it wraps the lines compared to msgmerge (and also msgcat, which uses the same wrapping as msgmerge). This is part of google/mdbook-i18n-helpers#32.

All in all, this means that you should try to submit PRs with files that have been touched lastby one of the Gettext tools: by msgcat or msgmerge.

However, I tried running the file thought msgcat -o po/zh-TW.po po/zh-TW.po just now, and I still get a lot of differences:

% git diff HEAD^ | diffstat
 zh-TW.po |13296 ++++++++++++++++++++++++++++++++++++++++++++++++-------------------------------------------------
 1 file changed, 6704 insertions(+), 6592 deletions(-)

So the changes are not primarily because of changes to the line numbers.

Looking through gh pr diff 1322 | bat -l patch, I see changes to files that are outside of Day 1:

gh pr diff 1322 | rg '\+#:' | cut -d : -f 2 | sort -u
 src/android/aidl/changing.md
 src/android/aidl/deploy.md
...
 src/bare-metal/alloc.md
 src/bare-metal/android.md
...
 src/exercises/android/morning.md
 src/exercises/bare-metal/afternoon.md
...
 src/exercises/day-2/afternoon.md
 src/exercises/day-2/book-library.md
...

So I think the zh-TV.po file needs more fine-grained splitting.

I recently found that I can msggrep out all files below the android/, bare-metal/, conconcurrency/, and async/ directories with this lovely incantation (in Zsh):

msggrep --location=src/{exercises/,}{async,bare-metal}{.md,"/*","/*/*","/*/*/*"} po/zh-TW.po

The rest (msggrep --invert-match) is Days 1 to 3. Getting the content of those days can be done similarly, but there are many more directories to match. Infact, now that I think of it, it might be easier to list the files explicitly to msggrep.

[henrif75]

The diff is large mostly because of the normalization.

What kind of normalization are you doing?

Yes, I used the mdbook-i18n-normalize at the end and most of the diff comes from the new lines and line numbers.

However, I tried running the file thought msgcat -o po/zh-TW.po po/zh-TW.po just now, and I still get a lot of differences:

% git diff HEAD^ | diffstat
 zh-TW.po |13296 ++++++++++++++++++++++++++++++++++++++++++++++++-------------------------------------------------
 1 file changed, 6704 insertions(+), 6592 deletions(-)

So the changes are not primarily because of changes to the line numbers.

When merging the translations, I did against an updated messages.pot. The diffs are coming mostly because of organic changes on the English text.
I'll resubmit the PRs anyway because of the mdbook-i18n-normalize, but to address the big diff we could:

• Refresh the PO file first or
• Just merge the translations against the current PO file without refreshing it.
  Any suggestions are welcome.

[mgeisler]

• Just merge the translations against the current PO file without refreshing it.

That is probably the right approach: separating the use of msgmerge (and mdbook-xgettext) from the translations.

With that, the steps become

1. Regenerate messages.pot once. This sets POT-Creation-Date to now.
2. Run msgmerge to merge messages.pot into the existing translation.
3. Split the PO file into smaller chunks with msggrep.
4. Send the chunks to the in-house translators.
5. When translations come back, use msgcat to join them with the PO file. Be careful that the translations don't just end up in the back of the PO file: the msgid has to exist in the PO file for msgcat to add the msgstr at the right spot. If the msgid changed, then perhaps msgmerge is the right tool, I'm not 100% sure here.
6. Open a PR with the changes.

This should ensure that the POT-Creation-Date header is set correct (to the date when the translation was submitted to the in-house translators, not to today's day or to any time in-between). It should also ensure that PRs only contain small amounts of changes.

If I understand correctly, the main change here is to only extract English strings rarely: once before sending the PO files to the translators.

[henrif75]

This should ensure that the POT-Creation-Date header is set correct (to the date when the translation was submitted to the in-house translators, not to today's day or to any time in-between). It should also ensure that PRs only contain small amounts of changes.

I had done that when I sent the file to the translators, with the difference that I sent a single file instead of the chunks. I think I can adapt your procedure by:

1. Update manually the POT-Creation-Date to the date when I refreshed the PO file with messages.pot.
2. Split the translated file into those chunks and merge them with the current zh-TW.po file, without refreshing again with messages.pot

Does it sound correct?

[henrif75]

I think now it's much more manageable?

[mgeisler]

I think now it's much more manageable?

Yes, it looks much better now! The diff actually loads in GitHub and from a quick skim, it looks like it's only adding translations! 🎉

[victorhsieh]

Publishing my progress so far. I'd suggest smaller patches next time, so that reviewers can process separately.

But in any case, thanks for the translation!

[henrif75]

Hi @victorhsieh ,
The check is failing probably because you're using a @gmail.com email that didn't accept the CLA, would like to check it out?
Thanks!

[victorhsieh]

/me making some progress slowly...

[victorhsieh]

LGTM with nits. Thanks for the translation!