How to Sync Translations for New Features?

[raclim]

Current Issue

Raised in #3656 by @cassiano!

When new features are added, the English text often gets merged before translations are in place. This leads to inconsistencies where:

• Some UI elements remain untranslated until someone notices and adds them later.
• Tests that depend on translation keys may fail or be harder to maintain.

Questions for Discussion

• Should new features be blocked from merging until at least the base translation keys are added?
• How do we want to handle updates when translations for all languages aren’t ready yet? For example, do we want to first merge with English placeholders and track missing translations separately? Or should werequire at least key/value stubs for all supported languages?
• Can we automate parts of this workflow (protentially utilizing Script to Identify Unused Translation Entries #3609)?

[mhsh312]

Hi! The only way to properly solve this would be to add translations for features before merging. But obviously that will delay the merge. And the delays will increase in the future as more languages are added.

Do we have a data on which are out most commonly used languages? We could translate our top 3 or top 5 before merging and then add the rest later.

For automation we could raise a single mega issue for missing translations and use the script to keep adding to-dos to the issue.

[cassiano]

Hi @mhsh312. I am glad we are having this conversation, so we can come up together with new ideas about this relevant subject.

First of all, what I have in mind is a (much) simpler process: the person who makes a PR (be it a bug fix or new feature) would be primarily responsible for identifying and creating new translation/localization keys in the en-US locale only (and of course provide the proposed english texts for them), which would always be the primary source of truth regarding i18n. PRs which do not follow this basic principle/rule simply would not be accepted.

This way new merges would not be affected by missing translations in any way, while providing a base code already prepared to support new translations easily.

When code is merged without fully supporting i18n in the base locale (en-US), it gets much harder later for others to identify and extract the translation keys. This happened to me recently, when working on this PR: #3656. I had a situation where the only solution I thought of was be to include an additional parameter (the t() function itself, used by React to provide the translation texts) in a particular function, potentially affecting other callers (I fortunately checked for that situation). I believe whoever did the original PR would have done in an much easier/better/faster way. That's my whole point with this discussion.

I like your idea of automating this process for the remaining languages, may be creating the corresponding issues (one per affected language) and the PR itself, marking missing translation keys in the particular l10n ("localization") file and removing unused keys (both done by the script I developed), so different people can work on them (in their particular languages).

For example, running the script against the es-419 locale with the current "develop" branch, my script clearly points out the need for translating 70 keys to spanish (while also removing dozens of unused keys), like the 3 shown below:

    "Help": {
      "Title": "Ayuda",
      "KeyboardShortcuts": "Atajos",
      "Reference": "Referencia",
      "About": "Acerca de",
      "ReportBug": "[NEEDS TRANSLATION - Nav.Help.ReportBug] Report a Bug",
      "ChatOnDiscord": "[NEEDS TRANSLATION - Nav.Help.ChatOnDiscord] Chat On Discord",
      "PostOnTheForum": "[NEEDS TRANSLATION - Nav.Help.PostOnTheForum] Post on the Forum"
    }

And this is what a spanish speaker sees today when he/she uses the editor (in production), proving the keys are really missing in that language:

The same applies to all remaining languages (besides en-US itself and pt-BR, which I have been working on over the last few weeks).

Let me know if you have any doubts about my proposal and I will be glad to help.

Cheers.

[cassiano]

I am also suggesting here (#3656) that code which uses dynamic translation keys, like this one:

  return (
    <a
      href={`#${targetId}`}
      className={linkClasses}
      onFocus={handleFocus}
      onBlur={handleBlur}
    >
      {t(`SkipLink.${text}`)}
    </a>
  );

would not be accepted anymore. Fortunately the above code is the only one I found in the codebase.

My proposal is to always use a TypeScript union type to define all potencial/valid values and a TS "exhaustiveness checking" to constrain and assure each value has a corresponding translation entry. Something like:

// May be in some other module.
export type SkipLinkOptions = 'PlaySketch';  // More could be added later, e.g. 'PlaySketch' | 'StopSketch'

interface SkipLinkProps {
  targetId: string;
  text: SkipLinkOptions;
}

export const SkipLink = ({ targetId, text }: SkipLinkProps) => {
  const [focus, setFocus] = useState(false);
  const { t } = useTranslation();
  const handleFocus = () => {
    setFocus(true);
  };

  const handleBlur = () => {
    setFocus(false);
  };
  const linkClasses = classNames('skip_link', { focus });

  let translatedText: string;

  switch (text) {
    case 'PlaySketch':
      translatedText = t('SkipLink.PlaySketch');
      break;
    default: {
      const exhaustiveCheck: never = text;
      throw new Error(`Unhandled case: ${exhaustiveCheck}`);
    }
  }

  return (
    <a
      href={`#${targetId}`}
      className={linkClasses}
      onFocus={handleFocus}
      onBlur={handleBlur}
    >
      {translatedText}
    </a>
  );
};

Please check the comments in that particular PR for more details.

[mhsh312]

Yeah this is a good idea. It will increase the complexity for each PR but in the long run will save a lot of time trying to hunt down missing (key-less) translations. Maybe we can finally put an end to the everyday "this part is not translated" PRs.

And if we agree on the automation of issue generation then I can take a crack at it after further discussion.

[cassiano]

Good to know we are reaching an agreement. You have used the right verb: HUNT DOWN. Sometimes this can be a real nightmare for those who have not participated in the feature creation.

I have no idea on how to automate the issue or even the PR creation (already linked to the issue). There may be APIs for both that could be used in a script.

When you say that "It will increase the complexity for each PR", I only partially agree, in the sense that it is much easier for those creating the feature to reason about their own (english) texts and place appropriate keys in the en-US l10n file. May be this will take additional 10-20 minutes from their time, which is insignificant when compared to the feature itself. Do you agree?

I believe we are already answering the "Questions for Discussion" raised by @raclim.

Count on me to stablish this new process, once all involved parts have been heard.

[cassiano]

Take this PR (#3644) as an example, where 2 German-related entries have been fixed. What about the other 76 (yes, seventy six) keys which are still missing, like shown in the attached file (identified by my script)?

translations.reviewed.json

Who on Earth would hunt them down manually??? Think about it for a minute.

Someone who is fluent in German could easily translate them in a matter of minutes, specially when using AI inside VS Code, Cursor etc. AI would suggest the proper translations and the person would only review (and fix) them.

We could go a litlle further and periodically (e.g. once per week) generate an issue in an automated way containing a summary of all missing keys, one line per language and properly sorted. Something like:

Language	Missing keys
us-EN	0
pt-BR	3
es-419	70
de	76
...	...

[cassiano]

It took me less than 2 minutes to do it using VS Code and Copilot:

Of course this would have to be reviewed by someone fluent in that language (not my case).

[cassiano]

Question: is this discussion valuable? Or I am going into too many details?

[mhsh312]

Your suggestion gave me another idea. We could use LLM to auto-translate whenever there is a new/untranslated keys and then if speakers of that language find a mistranslation, they can report that. We mostly have single words or small phrases in the UI and LLM can do that pretty consistently so I think the "mistranslation issues" will be far less than the "missing translation" issues. That way we won't have to wait for someone fluent in German to show up and do the translation. Until we get someone fluent in German, we could have AI generated translations which will be better placeholder than no translation at all.

[mhsh312]

Question: is this discussion valuable? Or I am going into too many details?

I think what you are suggesting is valuable but we need to go step by step.