stock strings

Handling stock strings in Delta Chat core

Objective

De-couple the way the core requests localised strings from the callback mechanism. This is the only callback use where the core needs the result of the callback, removing this allows more refactoring of the callback system and event delivery, enabling furture simplifications on the API (specifically thread handling).

Background

The DC_EVENT_GET_STRING event is used to get a localised string. Strings are identified by a numeric ID. Strings can contain placeholders like e.g. %1$s, %1$d, %1$@, %2$s, %2$d, %2$@. If the returned string contains these the core will substitute them with actual values, e.g. when the UI returns Member %1$s added the core would emit the message Member flub added.

The number in these paceholders are identifiers, currently only 1 and 2 are supported by the core, while the other variations exist to cater for the various translation formats used by different UI frameworks, e.g. %1$s and %2$s the format used by android (and GNU gettext) to represent strings and integers respectively while %1$@ is the format used by iOS. The core supports all these formats so that translations for the various systems remain native to them and require no special handling.

Lastly the callback uses the seconds data parameter to pass a “count” for where the placeholder is numeric. This allows translations to cater for singular vs plurals, e.g. 1 member added vs 2 members added.

Proposal

void dc_set_stock_string(dc_context_t* context, int id, char* singular, char* plural)

This function allows setting a translation string for any of the stock string IDs (see DC_STR_* in deltachat.h) passed in the id parameter. The translation string for singular is passed as singular while the translation string for the plural is passed as plural. The plural can be passed as NULL in which case the singular will be used for plural as well.

All translation strings can use any of the substitution placeholders currently used: %1$s, %2$s, %1$d, %2$d, %1$@ and %2$@.

If a translation string has not been set the default in deltachat::stock::StockMessage will be used.

void dc_clear_stock_string(dc_context_t* context)

Clears all the translation strings from the context.

Pros

• Core-rust remains translation-free
  • Maintains fallback strings

Cons

• New strings will be silently untranslated
  • Unless clients diligently check DC_STR_COUNT to detect changes.
• Languages have complicated plural rules not expressable here
  • https://mlocati.github.io/cldr-to-gettext-plural-rules/

Alternatives

Using gettext-rs

This would not involve clients at all. We’d have to handle translations & distribution somehow in rust-core.

Pros

• No API surface to clients

Cons

• Languages might not be in sync with client translations
• Distributing rust-core is more complicated
  • Other files involved

Discussion

Discussion on issue #629.