Translation Decisions, documentation and TODOs

[goneall]

On the 17 Dec 2024 tech call, an issue was raised that we should document translations in the "repository".

I've searched through all open and closed issues and pull requests for "translation" as well as the minutes repo for Asia and tech.

This issue summarizes outstanding decisions, undocumented decisions, documented decisions and process, and outstanding actions to support translating the spec.

Below are some detailed decisions that still seem unresolved:

• Agree on whether version tags in the spec and model repos should be considered immutable. See issue discussed in Publication source branches/tags and target URLs mapping/aliases #1155 On one of the tech call, the consensus of the attendees was immutable, but we didn't have Alexios on the call.
• Agree on the name of the tags that would be used once the translation for a particular language has been merged into the support branch. Proposals are to append the language code (e.g. 3.0.1-ja-ru-es), or just increment a suffix to the patch version (e.g. 3.0.1-l1, 3.0.1-l2, 3.0.1-l3). See discussion in Publication source branches/tags and target URLs mapping/aliases #1155
• Decide if we want to include translated summaries in the ontology - Decided yes on 7 Jan 2025 tech call

Below are decisions we've made that can be documented:

• Translations will be made on a separate branch or in a separate repository and when ready, a pull request will be made against the support branch for the version the translation is made for - see discussion in Publication source branches/tags and target URLs mapping/aliases #1155 Note that translations being targeted to the support directory are already documented in the README branches section. Also see 2024-11-05 minutes
• MKDocs will generate the languages (see 2024-05-21 minutes)
• We will implement a language dropdown for the website from MKDocs (see 2024-05-21 minutes)
• We will structure the spec repo documentation as separate directories for different languages under the docs directory - see 2024-06-06-translation minutes and 2024-06-18 minutes
• New translations will be tagged (see 2024-06-11 minutes)
• Document the decision in the comment below on how we tag the languages
• We will document that "en" is the normative language (see 2024-06-11 minutes)
  • Add English as normative notes #1170
  • Add notes on English as normative language spdx-3-model#946
• In the model, the class names, vocabularies, property names etc will not be translated - only the descriptions will be translated (see 2024-06-11 minutes)
• We will add a label to GitHub to track translations (done)
• We will create an email distribution list for translations (done)
• [ ]

Below are additional translation actions that need to be completed:

• Complete and merge PR Update CI to publish from spdx-spec "develop" and spdx-3-model "develop" branches #1164 to update the CI for the new branch structure
• In the model repo - spec parser needs to be updated to generate the language files
  • Generate markdown files for the languages
  • Generate summaries in the ontology as RDF comments in the different languages
• Update MKDocs and directory structure to separate the docs into separate language directories
• Update CI and MKDocs to publish MKDocs with the language dropdown
• Document that "en" is the normative language

Below are items I believe are already documented:

• Translation format for the SPDX model repo - this includes the model decisions documented in the 2024-05-21 minutes and 2024-06-06-translation minutes
• Branch structure for the SPDX model repo including documentation that translations should target the support branch

[goneall]

@kestewart @zvr @bact - let me know if you recall anything else we should capture here.

[bact]

@goneall thank you for the very detailed research! If there's anything that comes to my mind, I will post here.

[goneall]

from talking to @licquia we may be able to merge in PR #1141 without changing MKDocs or other changes then do the internationalization configuration after the merge - this way would have something to test with.

[bact]

Would be nice to have something to test with.

[zvr]

A number of comments on various bullet points. I'll number them so that any replies can refer to an index ;-)

1. Hard disagree on using multiple language codes on tags. This way madness lies. How would anyone know where to get a translation? We should have something with a single language code (e.g. 3.0.1-de). When you get this tag, other languages may also be present (English will definitely be there, but you may also get Japanese). It doesn't matter; you got the official de translation.

2. I understand the reluctance of moving tags -- I am not a big fan myself. But how else would someone (automatically) get the "latest and greatest" version with whichever completed translations included? For example, the automation that publishes the website. Do we expect to manually keep updating the CI every time we add a new translation?

3. Do we agree that translations will never be moved to develop/main branches? It might be implied from our branching/tagging strategy, but we'd better write it down explicitly.

4. Minor point about translations, not documented anywhere: there will be a piece of data (e.g., lines in a file) that lists all languages included in the repo.

5. I understand that this is the spec repo, but do we want to include info on handling of translations in the model repo here? What about the using repo?

[goneall]

In response to @zvr comment above:

1. - language codes

@zvr are you OK tagging 3.0.1-L1, 3.0.1-L2, ...? This would solve the length issue of the tags.

2. - moving tags and publishing

We can get the latest tag in a give branch as described in this StackOverflow article. We would get the latest tag for each release branch and use that for the publication.

3. - translations moving to develop/main branch

I was making a different assumption - so definitely needs to be documented ;) In thinking about it, we probably should do as suggested and not merge the translations to main or develop. The process of updating the translations would be something like:

1. A new version of the spec is released in English only
2. Compare the new version main branch (or the new release support branch) with the previous release support branch to identify which files have been added or changed
3. For each translation, create a pull request against the support branch for the new version copying unchanged text and translating any new or modified text.

[zvr]

1. If by L1 and L2 you refer to actual language codes, I'm fine with that. So, the series of tags in support/3.0 will be 3.0.1, 3.0.1-cn, 3.0.1-ja, 3.0.1-de if we merge Chinese, Japanese and German in order. Every one of these will include all the previous languages (and English).

[kestewart]

Makes sense to me, let's try it and adjust if it we've overlooked something.