"Fossies" - the Fresh Open Source Software Archive

Member "flutter-3.7.1/packages/flutter_localizations/README.md" (1 Feb 2023, 5302 Bytes) of package /linux/misc/flutter-3.7.1.tar.gz:

As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the last Fossies "Diffs" side-by-side code changes report for "README.md": 3.3.10_vs_3.7.0.

A hint: This file contains one or more very long lines, so maybe it is better readable using the pure text view mode that shows the contents as wrapped lines within the browser window.

Flutter Framework localizations

This package contains the localizations used by the Flutter framework itself.

See the localization README for more detailed information about the localizations themselves.

Adding a new string to localizations

If you (someone contributing to the Flutter framework) want to add a new string to the MaterialLocalizations, WidgetsLocalizations or the CupertinoLocalizations objects (e.g. because you've added a new widget and it has a tooltip), follow these steps (these instructions are for MaterialLocalizations, but apply equally to CupertinoLocalizations and WidgetsLocalizations, with appropriate name substitutions):

  1. For messages without parameters, add new getter

    String get showMenuTooltip;

    to the localizations class MaterialLocalizations, in packages/flutter/lib/src/material/material_localizations.dart;

    For messages with parameters, add new function

    String aboutListTileTitle(String applicationName);

    to the same localization class.

  2. Implement a default return value in DefaultMaterialLocalizations in the same file as in step 1.

    Messages without parameters:

    @override
String get showMenuTooltip => 'Show menu';

    Messages with parameters:

    @override
String aboutListTileTitle(String applicationName) => 'About $applicationName';

    For messages with parameters, do also add the function to GlobalMaterialLocalizations in packages/flutter_localizations/lib/src/material_localizations.dart, and add a raw getter as demonstrated below:

    /// The raw version of [aboutListTileTitle], with `$applicationName` verbatim
/// in the string.
@protected
String get aboutListTileTitleRaw;

@override
String aboutListTileTitle(String applicationName) {
  final String text = aboutListTileTitleRaw;
  return text.replaceFirst(r'$applicationName', applicationName);
}

  3. Add a test to test/material/localizations_test.dart that verifies that this new value is implemented.

  4. Update the flutter_localizations package. To add a new string to the flutter_localizations package, you must first add it to the English translations (lib/src/l10n/material_en.arb), including a description.

    Messages without parameters:

    "showMenuTooltip": "Show menu",
"@showMenuTooltip": {
  "description": "The tooltip for the button that shows a popup menu."
},

    Messages with parameters:

    "aboutListTileTitle": "About $applicationName",
"@aboutListTileTitle": {
  "description": "The default title for the drawer item that shows an about page for the application. The value of $applicationName is the name of the application, like GMail or Chrome.",
  "parameters": "applicationName"
},

    Then you need to add new entries for the string to all of the other language locale files by running:

    dart dev/tools/localization/bin/gen_missing_localizations.dart

    Which will copy the English strings into the other locales as placeholders until they can be translated.

    Finally you need to re-generate lib/src/l10n/localizations.dart by running:

    dart dev/tools/localization/bin/gen_localizations.dart --overwrite

    If you got an error when running this command, this issue might be helpful.

    TL;DR: If you got the same type of errors as discussed in the issue, run this instead:

    dart dev/tools/localization/bin/gen_localizations.dart --overwrite --remove-undefined

    There is a localization README file with further information in the lib/src/l10n/ directory.

  5. If you are a Google employee, you should then also follow the instructions at go/flutter-l10n. If you're not, don't worry about it.

Updating an existing string

If you or someone contributing to the Flutter framework wants to modify an existing string in the MaterialLocalizations objects, follow these steps:

  1. Modify the default value of the relevant getter(s) in DefaultMaterialLocalizations below.

  2. Update the flutter_localizations package. Modify the out-of-date English strings in lib/src/l10n/material_en.arb.

    You also need to re-generate lib/src/l10n/localizations.dart by running:

    dart dev/tools/localization/bin/gen_localizations.dart --overwrite

    This script may result in your updated getters being created in newer locales and set to the old value of the strings. This is to be expected. Leave them as they were generated, and they will be picked up for translation.

    There is a localization README file with further information in the lib/src/l10n/ directory.

  3. If you are a Google employee, you should then also follow the instructions at go/flutter-l10n. If you're not, don't worry about it.