Update translation guidelines for common pitfalls

[jacoblubecki]

Overview

Description

It appears one resource explaining how to use the command palette in VS code is not being replaced on this page. I don't have any other immediate examples on hand, but I can only imagine that whatever is causing this string not to translate may be affecting other resources as well.

What I've Tried

• I have tried clearing my local browser cache, viewing from other devices, etc.
• I have tried updating/re-reviewing the translation.

Documentation

Direct link: https://docs.wpilib.org/ja/latest/docs/zero-to-robot/step-4/creating-test-drivetrain-program-cpp-java.html

Translation reviewed 12+ days ago:

Current State:

Additional Info

I am open to doing work to resolve this from the code side (e.g. submitting a PR), but I would need support from wpilib first to root-cause the issue. The integration with the translation service is not clear to me and I am not sure if this is even something that can be fixed via PR.

[Daltz333]

Initial investigation leads that the translation is correctly getting synced to GitHub. You can see it's visible here, time to investigate why RTD is failing https://github.com/wpilibsuite/frc-docs-translations/blob/main/locale/ja/LC_MESSAGES/docs/zero-to-robot/step-4/creating-test-drivetrain-program-cpp-java.po

[Daltz333]

I replaced the text in transifex with a different translation (well not really a translation at all), to see if RTD was failing on some portion of the text.

[Daltz333]

The testing translation succeeded, so there is something about that specific string it's angry with

[jacoblubecki]

I checked the unicode and it doesn't seem to be using any particularly weird characters. I removed the leading space so I guess I can see if that's the problem...

[jacoblubecki]

@Daltz333 It look like the space at the beginning might have been the issue -- it looks like Transifex supports lint/error-checks for spaces at the beginning and end of source and translation strings. Would it be possible to enable that (at least as a warning)? Seems like it would be helpful if spaces at the start of a string quietly disable the translation.

---

As a note for context, Japanese essentially doesn't use the space character (even visual "spaces" are typically padding on a non-space character), however the space character is required by the reStructuredText parser to detect special directives (in this case, the :kbd:`...` thing). To get around this, we need to manually add spaces before/after these directives (except in this example, where the directive is at the beginning of the string). Since the sentence order is also different in Japanese, the directive that requires spaces ended up at the start of the sentence.

To illustrate a bit more, here are a few contrived examples:

Valid

:kbd:`foo` text after only
text before :kbd:`foo` text after

Invalid

:kbd:`foo`text after
text before:kbd:`foo`

Japanese strings are much closer to the invalid case.

I would guess other languages have similar limitations, so it might be a good note for the translations contributing page.