Where is the right place to describe language specific translation rules?

[chikoski]

@mgeisler

@keiichiw and I are thinking to have additional rules for those who works on Japanese translations, such as "Please refer to this table for your word choice for consistency". We have two possible options on the place to describe the JA translation specific rules as below:

• Option 1: Add a section to TRANSLATION.md for the language specific rules.
• Option 2: Add another document, e.g. TRANSLATION_ja.md, so that we can describe the rules in the independent file.

Our preference is the option 1 because of its simplicity. Our current analysis on the two options as follows:

Option 1 pros & cons:

• Pros: Convenient for contributors, especially for new contributors. We can understand all rules by referring to one file.
• Pros: Easier maintenance.
• Cons: Scalability. TRANSLATION.md can grow longer, and it can make contributors to find rules they need to refer to.

Option 2 pros & cons:

• Pros: Scalable.
• Cons: Inconvenience for contributors. Contributors needs to refer to several files to know all rules for the language they are going to work on.
• Cons: Maintenance. We need to maintain files describing language specific translation rules.

[mgeisler]

Hey @chikoski, @keiichiw, and @CoinEZ-JPN

I would suggest a third option: put this data right into the PO file for your language. I think that's the most flexible way and it means that the data is right where people will hopefully see it.

I've seen this being done on other projects which use Gettext: see the "Translation dictionary" at the top of da.po for an example (I worked on this many years ago).

[mgeisler]

As yet another alternative, you could use a file outside of the repository: I would suggest a discussion post here. You then update the first post based on what you agree in the discussion below. @keiichiw pointed me to the TranslationTable.md for the Japanese Rust Book — you will be able to use the full Markdown syntax in such a discussion post.

[CoinEZ-JPN]

In terms of inclusiveness, ideally we (users) would prefer @mgeisler last option (i.e. a file outside of the repository)

However, favoring realistic convenience, maybe just a broader guideline on what/where to reference when translating may be more acceptable.
For instance, in this specific case, I am referencing a combination of the following;

• TranslationTable.md
• Rust Book 日本語版
• Rust by Example 日本語版
• Embedded Rust Techniques

more or less in order of priority to make the translation less questionable.

[chikoski]

Thanks for sharing your thoughts. The third option sounds good to me. I would start with adding reference points to the head of ja.po file.

[mgeisler]

So maybe discuss here and then move things to the ja.po file when a consensus is reached?