[feature/modular-localization] Modular localization

[felix-schwarz]

Description

Switches OCLocalized, OCLocalizedString and String.localized from NSLocalizedString and NSBundle to OCLocale, allowing complex customization of localized strings with variables, value sources and complete text replacements.

That makes it possible to change the localization of specific strings via class settings. To f.ex. change Settings to Preferences (en) and Präferenzen (de), one would use:

<key>locale.overrides</key>
<dict>
	<key>Settings</key>
	<dict>
		<key>en</key>
		<string>Preferences</string>

		<key>de</key>
		<string>Präferenzen</string>
	</dict>
</dict>

Furthermore, localized strings can now contain variables that are getting replaced during localization.

Global variables

For example:

Log.log("{{app.name}} {{app.process}} {{app.version}} {{app.build}} {{device.model}} {{device.model-id}} {{os.name}} {{os.version}}".localized)

prints

ownCloud ownCloud 11.7.1 201 iPhone x86_64 iOS 15.0

when run in the Simulator.

Template variables

Template variable support can be used this way:

Log.log("{{product}} is awesome!".localized([ "product" : "ownCloud" ]))

prints

ownCloud is awesome.

In the Localized.strings file, templates appear like any other string:

"{{product}} is awesome!" = "{{product}} ist großartig!";

Global vs. template variables

As a convention to avoid conflicts:

• global variables must use dot syntax (i.e. app.name), whereas
• template variables must not use dot syntax (i.e. appName)

Related Issue

https://github.com/owncloud/enterprise/issues/4801

Screenshots (if appropriate):

Changes in en	Changes in de

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.
• Added changelog files for the fixed issues in folder changelog/unreleased

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[jesmrec]

QA checks:

• Set string in other language & switch to that language
• Set device in a language in which a string is not set -> string in most preferred one in device settings
• Set device in a language without locale in Branding.plist (regression)

[jesmrec]

@fschwarz When i set a device in a language (f.ex. Spa) and no entries for spanish in locale.overrides for an specific string, it's getting the first in the list, no matter which one. Is that correct? F.ex:

<key>Settings</key>
			<dict>
				<key>de</key>
				<string>Präferenzen</string>
				<key>fr</key>
				<string>Paramètres</string>
			</dict>

the device in Spanish language will display the German translation because it is the first in the list. If i'd add the english, i will take english. Does that mean that english is default and "mandatory"?

[felix-schwarz]

@fschwarz When i set a device in a language (f.ex. Spa) and no entries for spanish in locale.overrides for an specific string, it's getting the first in the list, no matter which one. Is that correct? F.ex:

No, that's not correct. For overrides like this, the app will pass a list of available localization languages (de, fr in your example) to iOS and iOS will then return them ordered by user preference (with the app using the most preferred one). That order can be changed by the user in iOS Settings > General > Language & Region > Preferred language order.

You can get the list from the system by pausing execution of the app, then typing

po NSLocale.preferredLanguages

in the debugger. For my iPhone, it returns:

<__NSArrayM 0x13bf20390>(
de-DE,
en-DE
)

I'm not sure what language iOS will return if none of the languages is in the list of preferred languages. The documentation hints at it finding the next best locale based on the user's region: https://developer.apple.com/documentation/foundation/nsbundle/1417249-preferredlocalizationsfromarray?language=objc

If that doesn't provide the needed results, I can add a fallback option that checks if NSLocale.preferredLanguages contains any of the languages that the override provides - and if it doesn't, uses a particular localization instead.

the device in Spanish language will display the German translation because it is the first in the list. If i'd add the english, i will take english. Does that mean that english is default and "mandatory"?

Based on how locale selection appears to work, I'd assume it picks the next best understood language for the average person in the user's region. So if you have set es and en as preferred languages in iOS Settings, iOS seems to assume the average person in your region is more likely to understand de than fr, and also more likely to understand en than de (or simply picks en because it's (likely) in your preferred languages).

[jesmrec]

Thanks for the clear explanation @felix-schwarz. As i can see, this feature is heavily tied to the language setup in the device, so it is not realistic to set more tests beyond checking if the correct locale is being set in the correct place. Number of combinations is exponential to the number of languages.

I'm not sure what language iOS will return if none of the languages is in the list of preferred languages. The documentation hints at it finding the next best locale based on the user's region: https://developer.apple.com/documentation/foundation/nsbundle/1417249-preferredlocalizationsfromarray?language=objc
If that doesn't provide the needed results, I can add a fallback option that checks if NSLocale.preferredLanguages contains any of the languages that the override provides - and if it doesn't, uses a particular localization instead.

I've tested this, with a quick example

	<key>locale.overrides</key>
	<dict>
		<key>Settings</key>
		<dict>
			<key>fr</key>
			<string>Parameteres</string>
		</dict>
	</dict>

Preferred languages in device (no fr):

The displayed string is the french one.

It sounds like a corner case, since the enterprise world will use the most common language for all users involved. So, it is up to you to add the fallback you mentioned above, just in case.

[felix-schwarz]

@jesmrec The locale override works by

• passing the list of available override languages to -preferredLocalizationsFromArray: which returns them, reordered in order of user preference
• using the locale for the language at the top of the returned list

If only one language is available, it'll pass ["fr"] and get ["fr"] back, so it'll use fr.

If three languages are available, f.ex. ["fr", "es", "de"], it'd return ["es", "de", "fr"] for your setup, and es would get used.

I think we can leave it as is for now, since localization overrides would typically be provided for all languages used in an organization. If the need arises nonetheless, we can still add a fallback option locale.override-fallback-language to specify a language to fall back to if there are no matching locales for what the user has set up on the device.

[jesmrec]

I think we can leave it as is for now, since localization overrides would typically be provided for all languages used in an organization. If the need arises nonetheless, we can still add a fallback option locale.override-fallback-language to specify a language to fall back to if there are no matching locales for what the user has set up on the device.

totally agreed. Let's move this forward having in mind the corner case and its fix, just in case it arises.

[michaelstingl]

I think we can leave it as is for now, since localization overrides would typically be provided for all languages used in an organization. If the need arises nonetheless, we can still add a fallback option locale.override-fallback-language to specify a language to fall back to if there are no matching locales for what the user has set up on the device.

Limit the languages in the app, in case big organisations want more control about it? (someday, maybe… not urgent)