L10n Review PR

[caugner]

Description

(Ignore this PR.)

Motivation

Additional details

Related issues and pull requests

[peiying2]

In addition to the comments to the strings, here are a few more general comments:

• Is there a staging URL to verify the translation? An example from mozilla.org project
• en vs en-US locale - In case en-US has US specific content that's not applicable to other languages/countries, it's a better practice to use en as the source for localizable content
• Speaking of locales, the Country code should be in capital letters, so en-US, pt-BR, zh-CN, zh-TW
• Mozilla brand and product names: when referencing names, this approach ensures consistency. If there are more pages to add to the project, you can create a separate files for names only, and other pages can reference to it.
• Links: I didn't call them all out but only commented in one string. They are typically coded like this `{ -brand-name-mozilla-corporation}.
• The page lacks comments for context. Please add them even if it seems obvious in some cases. Please note the differences in comments for a section and comment for one string.

[peiying2]

What is this variable for? Or is it for formatting?

[bcolsson]

Looking into this it seems its just the character *. It's best to either use the character itself here, or if there area reasons for not wanting localizers to be able to adjust it, then perhaps its best to remove it from the string and style on the backend.

[peiying2]

What are shown in { $supported } and { $unsupported }? Add a comment will provide context will help.

[peiying2]

Need a comment on what the variable is for, like the kind of queries.

[peiying2]

So this string is about how fast results can be found, not how many results found in X number of articles.

[peiying2]

Is it better to change the websites and scan numbers to variables to minimize the needs for updates in the future?

[peiying2]

Need examples for vendor and prefix look like in this context.

[peiying2]

Nitpick, maybe changing the second This feature to It.

[peiying2]

Remove the comma before since 2005.

[peiying2]

Can we make 1998–2024 dynamically updated?

[peiying2]

For links, we typically use this format <a href="{ $moco }">Mozilla Corporation</a> for example.

[bcolsson]

I think this depends on the backend, it appears that's how bedrock is doing things for their footer links, but might not be applicable in this case.

[bcolsson]

In addition to the individual comments - we should consider if this needs separate brand terms for:
Mozilla
Mozilla Corporation
Mozilla Foundation
HTTP Observatory

This depends on how frequently new strings will be introduced once localization begings and how likely they'd include these terms.

[bcolsson]

Suggested change

	article-footer_last-modified = This page was last modified on <time data-l10n-name="date">{ $date }</timestamp> by <a data-l10n-name="contributors">MDN contributors</a>.
	article-footer_last-modified = This page was last modified on <timestamp data-l10n-name="date">{ $date }</timestamp> by <a data-l10n-name="contributors">MDN contributors</a>.

Tags don't match

[bcolsson]

Looking into this it seems its just the character *. It's best to either use the character itself here, or if there area reasons for not wanting localizers to be able to adjust it, then perhaps its best to remove it from the string and style on the backend.

[bcolsson]

This is more stylistic - but can we consistently use dashes - instead of underscores for string IDs?
E.g. article-footer-last-modified

[bcolsson]

Could you include a comment to describe variables? Something like the below:

Suggested change

	article-footer_source_title = Folder: { $folder } (Opens in a new tab)
	# Variables:
	# $folder (String) - Link to github folder
	article-footer_source_title = Folder: { $folder } (Opens in a new tab)

[bcolsson]

Could you include a comment for the variable here and similar date variables below?

Suggested change

	baseline_high_extra = This feature is well established and works across many devices and browser versions. It’s been available across browsers since { $date }.
	# Variables:
	# $date (String) - a localized date string in format Month YYYY (e.g. December 2024)
	baseline_high_extra = This feature is well established and works across many devices and browser versions. It’s been available across browsers since { $date }.

[bcolsson]

Should HTTP Observatory be localized or treated as a brand term / left unlocalized?

[bcolsson]

Noting here that there seem to be string IDs here that don't match anything in en-US source.

[bcolsson]

This likely needs a comment to say what "No" is refuting here (e.g. is this refusing some request, or is it short for No compatibility or something else?)

[bcolsson]

Suggested change

	sidebar-filter-matches = { $matches ->
	[0] No matches
	[1] { $matches } match
	*[other] { $matches } matches
	}
	sidebar-filter-matches = { $matches ->
	[0] No matches
	[one] { $matches } match
	*[other] { $matches } matches
	}

[bcolsson]

Suggested change

	obs_mdn = The HTTP Observatory provides effective security insights, guided by Mozilla's expertise and commitment to a safer and more secure internet and based on well-established trends and guidelines.
	obs_mdn = The HTTP Observatory provides effective security insights, guided by Mozilla’s expertise and commitment to a safer and more secure internet and based on well-established trends and guidelines.

[caugner]

• Is there a staging URL to verify the translation? An example from mozilla.org project

Currently, all PRs by privileged users lead to a review deployment, and we'll extend this to non-privileged users eventually.

• en vs en-US locale - In case en-US has US specific content that's not applicable to other languages/countries, it's a better practice to use en as the source for localizable content

MDN is only served in en-US, not en, i.e. en redirects to en-US.

• Speaking of locales, the Country code should be in capital letters, so en-US, pt-BR, zh-CN, zh-TW

Fixed in ea86ac4 (not on this branch).

• Mozilla brand and product names: when referencing names, this approach ensures consistency. If there are more pages to add to the project, you can create a separate files for names only, and other pages can reference to it.

• Links: I didn't call them all out but only commented in one string. They are typically coded like this `[{ -brand-name-mozilla-corporation}]({ $moco }).

• The page lacks comments for context. Please add them even if it seems obvious in some cases. Please note the differences in comments for a section and comment for one string.

Thanks, I added action items for us, to migrate to kebab-case, use comments, and consider using terms.

[peiying2]

@caugner Any update on this?

[LeoMcA]

Hey @peiying2 - sorry about the wait, the l10n work so far was just to ensure we had a functional API for development, rather than anything remotely usable by localisers. I've turned my attention to this now, but I need to explain a bit of our philosophy here:

I'm not a huge fan of writing strings out of context: I think it makes making mistakes easier, and is much harder for code contributors. Because of that, I've designed an API around inlining strings, like this (see the this.l10n template tags):

html`<div class="language_switcher__remember">
  <mdn-switch
    @toggle=${this._togglePreferredLocale}
    ?checked=${this._isLocalePreferred}
    >${this.l10n`Remember language`}</mdn-switch
  >
  <mdn-button
    variant="plain"
    .icon=${infoIcon}
    icon-only
    href="https://github.com/orgs/mdn/discussions/739"
    target="_blank"
    title=${this
      .l10n`Enable this setting to always switch to the current language when available. (Click to learn more.)`}
    >${this.l10n`Learn more`}</mdn-button
  >
</div>`

I've got a proof of concept string extractor which produces a Fluent file like the following:

remember-language-8ut5 = Remember language
enable-this-setting-to-always-sw-1ah2 = Enable this setting to always switch to the current language when available. (Click to learn more.)
learn-more-1o3l = Learn more

We do also support manually specifying the id, using syntax like this.l10n("default")`OS Default`. Otherwise for more complex strings - with arguments, etc. - we don't inline them (for now, at least).

I've got a bunch of questions about where to go from here:

1. How much do IDs matter: you'll see I've made a slug out of the string, truncated it, and appended a hash (so e.g. "hello" and "Hello!" don't clash). Could I do away with the slug entirely and just use hashes? Or would it be best to not use hashes at all, and error in the case of clashes, telling the developer to manually specify the ID.

2. Is there any issue in Pontoon with using a collection of many small Fluent files, rather than one big one with everything in? It could make life a lot easier for ID generation and overall performance if we have one Fluent file per component or even js file. How does Pontoon handle duplicated strings across files - if memory serves it has some kind of "this string is similar to this one already localised" functionality - so I hope it's not too bad for localisers.

3. I'm aware that the same string in different contexts in one locale can require multiple strings in another. Are there sensible assumptions that can be taken here (e.g. the same English string used twice in the same component is probably localised the same), or is it a hard requirement that each string be unique in the Fluent file? How tight is the feedback loop from Pontoon: will it be easy for localisers to ping us and tell us that we need two separate IDs in this context?

I think that's it for now: I've noted your points about using comments and brands - I've got some ideas for how to implement that with the inline string approach - thank you!

[peiying2]

Hello @LeoMcA

I will have my colleague @bcolsson to answer the more technical questions. I will address the questions below for the time being

2. Is there any issue in Pontoon with using a collection of many small Fluent files, rather than one big one with everything in? It could make life a lot easier for ID generation and overall performance if we have one Fluent file per component or even js file. How does Pontoon handle duplicated strings across files - if memory serves it has some kind of "this string is similar to this one already localised" functionality - so I hope it's not too bad for localisers.

Most of the Fluent based web projects have multiple files, such as Relay, Mozilla.org and Firefox.com. They tend to provide better context through the file names. It's easier to manage than having one big file.

Having a smaller file is a lot easier for ID generation. Both firefox.com and mozilla.org use the file name as part of the string ID and the first few words in the string to make up the string ID. Here is an example.

Yes, Pontoon has a translation memory feature that shows localizers translations of identical or similar source content and rate them in % on the level of matches. Localizers can select the correct one based on context. Don't worry about duplicates.

3. I'm aware that the same string in different contexts in one locale can require multiple strings in another. Are there sensible assumptions that can be taken here (e.g. the same English string used twice in the same component is probably localised the same), or is it a hard requirement that each string be unique in the Fluent file? How tight is the feedback loop from Pontoon: will it be easy for localisers to ping us and tell us that we need two separate IDs in this context?

Preferably different ID for each of the strings even if they are the same. I remember a case where the same word is used for footer and navigation but in Turkish, they use different words for the same English words.

Add context in the comments. If there are variables, provide examples how the variable would show up. If localizers have questions or need clarification, there is a comment field associated with each string. They usually ask questions and the l10n team will relay the question.

You probably have seen these documents already. It's worth checking it out or share with the team if you haven't.

[peiying2]

@LeoMcA I want to share a document the Bedrock team put together on writing code in Fluent with L10n in mind.

[bcolsson]

How much do IDs matter: you'll see I've made a slug out of the string, truncated it, and appended a hash (so e.g. "hello" and "Hello!" don't clash). Could I do away with the slug entirely and just use hashes? Or would it be best to not use hashes at all, and error in the case of clashes, telling the developer to manually specify the ID.

Speaking in best practices: IDs matter quite a bit to both those reviewing the source strings (us) and those translating the strings. They often provide important context to understand things like whether something is a button, header, etc. In other projects, we often use name spacing to both keep IDs unique, while also making things easier to find - especially when trying to find which instance of a common string (e.g. "Password" or "Sign in") is referring to.

Other challenges I see:

• Handling updates to strings. If a string needs to change we need to update the string ID to ensure that translations are re-triggered. (See here for details.) Using hashes would conceivably ensure a new string is created, but how do you know what the old string was for removal? There's also times when you want to make a slight change to a string and not update translations (adding a comma/period or changing capitalization), and a hash would make that impossible. It also makes it hard for string reviewers to determine whether strings are new or updated (and again, if the string ID isn't labeled in the code then it's hard to find where the string is used).
• Touched on above: if a string is no longer used/removed in code, how would we know which strings are safe remove?
• Generating Fluent strings by extracting them from code would also mean that by default we aren't adding comments to them.

My recommendation here would be to always manually specify IDs, name space them, but still have something check that there aren't duplicate IDs.

Is there any issue in Pontoon with using a collection of many small Fluent files, rather than one big one with everything in? It could make life a lot easier for ID generation and overall performance if we have one Fluent file per component or even js file. How does Pontoon handle duplicated strings across files - if memory serves it has some kind of "this string is similar to this one already localised" functionality - so I hope it's not too bad for localisers.

In addition to what Peiying mentioned about translation memories and name spacing, I'll note that we need to have unique string IDs regardless if they are in different files. (So you can't have a page-title in File A and also a page-title in File B, this is where name spacing comes in handy.)

I'm aware that the same string in different contexts in one locale can require multiple strings in another. Are there sensible assumptions that can be taken here (e.g. the same English string used twice in the same component is probably localised the same), or is it a hard requirement that each string be unique in the Fluent file? How tight is the feedback loop from Pontoon: will it be easy for localisers to ping us and tell us that we need two separate IDs in this context?

Best practices for localization strings is to prefer WET versus DRY code. These are hard errors to spot, especially if we aren't providing additional context via comments / string IDs.

[peiying2]

@LeoMcA let us know if anything is unclear in our comments. We can also arrange a call to go over some of the issues if it's easier.

[LeoMcA]

Apologies, I was wrapped up getting fred ready for launch.

All great advice: thank you. #452 is a first step, making every string technically localisable, which we can build upon following your advice to improve the l10n experience.