Localizations

[cortig]

You need to add localizations in multiple languages for the app :->

[Krinkle]

I'd be happy to translate the app in Dutch.

If you'd be interested in crowd-sourcing this in a peer-reviewed open-source friendly way, consider https://translatewiki.net/. They're mainly known as the translate hub for the web apps of Wikipedia and OpenStreetMap, and translate many other open-source projects as well. I have set up projects with TWN as developer before, and am also a translator there.

I'd be happy to help out, answer any questions you might have, and/or act as liasion for the foreseeable future.

[kevinm6]

I could help translate NNW into Italian

[damrtom]

I could help translate NNW into French!

[cortig]

On Nov 28, 2020, at 05:30, damrtom ***@***.***> wrote: I could help translate NNW into French!

Considering that the original version of NNW was entirely localized in French, I suspect a good chunk of the current app has strings that already have a match. There are also extensive glossaries that could help easy the work tremendously. For the record, it’s not that I “abandoned” localizing the app at some point. I offered repeatedly when it changed hands and never got any reply… And then it came back home and my understanding is that needed some work to be localizable again. Corentin

[flpStrri]

When you start working on this I can help with Brazilian Portuguese.

[ericlamarca]

I'd be happy to do Catalan

[sebdanielsson]

I could do Swedish.

[flappybriefs]

I could help translate NNW into Chinese!

[cfuentea]

Count with me to translate it to Spanish 🙌🏻

[Bill-Haku]

I could help translate NNW into simplified Chinese and traditional Chinese

[stuartbreckenridge]

Current State

The codebase makes extensive use of NSLocalizedStrings, generally in the format of:

NSLocalizedString("Are you sure you want to delete the “%@” feed?", comment: "Feed delete text")

or, in SwiftUI:

Text("Are you sure you want to delete the “%@” feed?", comment: "Feed delete text")

With no changes to the above, a Localization Export would generate an en.xcloc file using the NSLocalizedString value as the key and English (development language) translation:

Key	English	Comment
Are you sure you want to delete the “%@” feed?	Are you sure you want to delete the “%@” feed?	Feed delete text

Further, all NSLocalizedStrings—just over 300 for the iOS target—would end up in a single Localizable.strings file.

---

Proposal

This proposal follows the principle that localization is not done at source, i.e., in code, but in *.strings—Internationalization of the codebase. This will result in a significant—though hopefully one-time changes—to the way localized strings are managed.

1. Keys

• Keys should be keys and not a mirror of the development language.
  • This ensures that changes to the base translation don't affect the key. (If the base language is used as the key, and the base translation changes, all translations for the old key would need to be reapplied to the new key. With this approach, you can change the base translation without impacting the key or other language translations.)
  • This makes it easier to spot non-localized strings at runtime.
  • It removes English norms from the keys (grammar, punctuation).
• They should follow as consistent a format as possible:
  • <ui_element>.<ui_position>.<hyphen>-<separated>-<content>

Concretely, non-localized strings would display as keys, while localized strings would display translated:

In code, this approach would manifest as follows:

let addNewFolderTitle = NSLocalizedString("keyboard.command.new-folder", comment: "New Folder")

let localizedMenuText = NSLocalizedString("button.title.mark-all-as-read.%@", comment: "Mark All as Read in ”feed”. The variable name is the feed name.")
let title = NSString.localizedStringWithFormat(localizedMenuText as NSString, webFeed.nameForDisplay) as String

In *.strings:

/* New Folder */
"keyboard.command.new-folder" = "New Folder";

In xcloc:

Key	English	French	Comment
button.title.mark-all-as-read.%@	Mark All as Read in “%@”	Marquez tout comme lu dans “%@”	Mark All as Read in ”feed”. The variable name is the feed name.

Important: with this approach, we will need to audit all strings, convert them to the above convention, and provide base (English) translations.

2. Comments

• All strings that require localization should be audited to ensure that their comment clearly articulates the purpose and content in the development language — English.
• All strings that require localization from here on must include a clear comment.
• Where strings have multiple variables, the comment must describe the ordering.

3. Organisation

As discussed above, all strings will end up in a single (per target) Localizable.strings file without changes.

For the main targets, this proposal suggests (though it is not required) taking an active approach and defining where our strings will live based on the screen/major feature in which they are being used:

Feeds.strings
Timeline.strings
Article.strings
Settings.strings

NSLocalizedString("alert.message.delete-feed.%@", tableName: "Feeds" comment: "Asks the user for confirmation that they wish to delete a folder. The variable provided is the feed name. In English, the message is: Are you sure you want to delete the “%@” feed?")

The only exclusion to this would be common strings, e.g., basic button titles like "Done", "Dismiss", or "Cancel". They can be included in a Shared.strings file and shared amongst the targets.

NSLocalizedString("button.title.done", tableName: "Shared" comment: "Button title: Done")
Text("button.title.done", table: "Shared", comment: "Button title: Done")

Extensions (Share, Widget, etc.) are small enough that their translations can be stored in their own Localizable.strings file.

Future Translations

We will need to be disciplined for each release to ensure that new strings are localized. The way I see this working is as follows:

1. Text("button.title.add-mastodon-user", table: "Settings", comment: "Add Mastodon User")
2. We do an Export Localization
3. Add the Base Localization (English) and Import
4. Before Release, Export again and translators update es, fr files (etc)
5. We import, test...
6. ...and then we should be good to go.

Updates to Existing Translations

Updates to existing translations must be done in existing .strings files. Xcode will not overwrite existing translations on import.

---

Reference Materials

1. Why Internationalize Your Code Base
2. Apple — Internationalizing Your Code
3. WWDC '22: Build Global Apps - Localization by Example
4. WWDC '21: Streamline Your Localized Strings
5. Metatext localizations
6. Mastodon for iOS localizations
7. Phrase — iOS Internationalization and Localization tutorial
8. IceCubes for Mastodon

[kevinm6]

So @stuartbreckenridge, @vincode-io we have to follow this to contribute on NNW Localization?
We just fork, add Lang.strings and create a PR?

[vincode-io]

@kevinm6 No decisions have been made yet on how we will be implementing localization.

[stuartbreckenridge]

A proof of concept is available on this branch.

It converts NetNewsWire (both iOS and macOS) to key-based strings and includes, for ease of a demo, both English (US/base) and English (UK). Adding a new language is done via the Project Inspector, which will automatically add the appropriate .strings resources for that language.

Translation can then be done via Export Localizations, and then an import of the language specific xcloc.

[moonpieq]

I seted up rss on my mum's phone so she can read NYT and the WSJ from China, I would be more than happy to help localize the app to Chinese both simplified and traditional.

[I7T5]

Help translate to Chinese +1

[kevinm6]

Hi @stuartbreckenridge!
Are there any guidelines to contribute with localization, so far?

[Jerry23011]

@kevinm6 The guidelines are in the Technotes
https://github.com/Ranchero-Software/NetNewsWire/blob/main/Technotes/Localization.md

[kevinm6]

@kevinm6 The guidelines are in the Technotes

https://github.com/Ranchero-Software/NetNewsWire/blob/main/Technotes/Localization.md

Oh, perfect!
Thank you, @Jerry23011 , I didn't notice them.

[stuartbreckenridge]

@kevinm6 Are you planning on providing a localization?

[kevinm6]

@stuartbreckenridge yes!
I could provide an Italian localization

[kevinm6]

Sorry, @Jerry23011 , I’m noticing that some keys are left original (like “On My iPhone” and similar)!
Is that a choice or also that keys are going to be localized in the future?

[Jerry23011]

I already had them ready (see file below), but if you check the source file, you'll notice that they can't be imported yet.
Account.xcloc.zip

[stuartbreckenridge]

@kevinm6 As per this PR I still have some work to do on the Account package.

[stuartbreckenridge]

@Jerry23011 / @kevinm6 I will have Account internationalized tomorrow. #4018

[kevinm6]

@stuartbreckenridge okay, thank you!
So, I'll start from the files that are already localized from the PRs in Chinese of @Jerry23011 and then I'll pull the new changes when they are done!

[Jerry23011]

@Jerry23011 / @kevinm6 I will have Account internationalized tomorrow. #4018

Thanks!

I'll start from the files that are already localized from the PRs in Chinese of @Jerry23011

I will probably PR to make two new changes in the near future.

P.S. @kevinm6 Could you perhaps join in the #work channel in Slack? I feel that it would be more convenient for us to chat there