From 5fa8de05ee857a77ee392bd18c34510a127449e4 Mon Sep 17 00:00:00 2001 From: Ian Hickson Date: Thu, 24 Aug 2023 14:54:56 -0700 Subject: [PATCH] l10n-related documentation improvements (#133114) --- .../localization/bin/gen_localizations.dart | 18 +++++++++--------- .../lib/src/cupertino/localizations.dart | 1 - .../src/material/material_localizations.dart | 5 +++-- .../flutter/lib/src/widgets/localizations.dart | 2 +- .../lib/src/l10n/README.md | 6 ++---- .../lib/src/l10n/material_en.arb | 4 ++-- 6 files changed, 17 insertions(+), 19 deletions(-) diff --git a/dev/tools/localization/bin/gen_localizations.dart b/dev/tools/localization/bin/gen_localizations.dart index 91490fec32..af70e23689 100644 --- a/dev/tools/localization/bin/gen_localizations.dart +++ b/dev/tools/localization/bin/gen_localizations.dart @@ -2,11 +2,11 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. -// This program generates a getMaterialTranslation() and a -// getCupertinoTranslation() function that look up the translations provided by +// This program generates getMaterialTranslation(), getCupertinoTranslation(), +// and getWidgetsTranslation() functions that look up the translations provided by // the arb files. The returned value is a generated instance of a -// GlobalMaterialLocalizations or a GlobalCupertinoLocalizations that -// corresponds to a single locale. +// GlobalMaterialLocalizations, GlobalCupertinoLocalizations, or +// GlobalWidgetsLocalizations object that corresponds to a single locale. // // The *.arb files are in packages/flutter_localizations/lib/src/l10n. // @@ -40,8 +40,8 @@ // ``` // // If the data looks good, use the `-w` or `--overwrite` option to overwrite the -// packages/flutter_localizations/lib/src/l10n/generated_material_localizations.dart -// and packages/flutter_localizations/lib/src/l10n/generated_cupertino_localizations.dart file: +// generated_material_localizations.dart, generated_cupertino_localizations.dart, +// and generated_widgets_localizations.dart files in packages/flutter_localizations/lib/src/l10n/: // // ``` // dart dev/tools/localization/bin/gen_localizations.dart --overwrite @@ -543,19 +543,19 @@ void main(List rawArgs) { // Maps of locales to resource key/value pairs for Widgets ARBs. final Map> widgetsLocaleToResources = >{}; - // Maps of locales to resource key/attributes pairs for Widgets ARBs.. + // Maps of locales to resource key/attributes pairs for Widgets ARBs. // https://github.com/googlei18n/app-resource-bundle/wiki/ApplicationResourceBundleSpecification#resource-attributes final Map> widgetsLocaleToResourceAttributes = >{}; // Maps of locales to resource key/value pairs for Material ARBs. final Map> materialLocaleToResources = >{}; - // Maps of locales to resource key/attributes pairs for Material ARBs.. + // Maps of locales to resource key/attributes pairs for Material ARBs. // https://github.com/googlei18n/app-resource-bundle/wiki/ApplicationResourceBundleSpecification#resource-attributes final Map> materialLocaleToResourceAttributes = >{}; // Maps of locales to resource key/value pairs for Cupertino ARBs. final Map> cupertinoLocaleToResources = >{}; - // Maps of locales to resource key/attributes pairs for Cupertino ARBs.. + // Maps of locales to resource key/attributes pairs for Cupertino ARBs. // https://github.com/googlei18n/app-resource-bundle/wiki/ApplicationResourceBundleSpecification#resource-attributes final Map> cupertinoLocaleToResourceAttributes = >{}; diff --git a/packages/flutter/lib/src/cupertino/localizations.dart b/packages/flutter/lib/src/cupertino/localizations.dart index 02cb25970f..2262d55f45 100644 --- a/packages/flutter/lib/src/cupertino/localizations.dart +++ b/packages/flutter/lib/src/cupertino/localizations.dart @@ -57,7 +57,6 @@ enum DatePickerDateOrder { /// /// * [DefaultCupertinoLocalizations], the default, English-only, implementation /// of this interface. -// TODO(xster): Supply non-english strings. abstract class CupertinoLocalizations { /// Year that is shown in [CupertinoDatePicker] spinner corresponding to the /// given year index. diff --git a/packages/flutter/lib/src/material/material_localizations.dart b/packages/flutter/lib/src/material/material_localizations.dart index 21d7515b55..8cfd4b046a 100644 --- a/packages/flutter/lib/src/material/material_localizations.dart +++ b/packages/flutter/lib/src/material/material_localizations.dart @@ -179,10 +179,11 @@ abstract class MaterialLocalizations { /// Label indicating that a given date is the current date. String get currentDateLabel; - /// Label for the scrim rendered underneath the content of a modal route. + /// Label for the scrim rendered underneath a [BottomSheet]. String get scrimLabel; - /// Label for a BottomSheet. + /// Label for a [BottomSheet], used as the `modalRouteContentName` of the + /// [scrimOnTapHint]. String get bottomSheetLabel; /// Hint text announced when tapping on the scrim underneath the content of diff --git a/packages/flutter/lib/src/widgets/localizations.dart b/packages/flutter/lib/src/widgets/localizations.dart index 72f58ad1df..499e21bdf9 100644 --- a/packages/flutter/lib/src/widgets/localizations.dart +++ b/packages/flutter/lib/src/widgets/localizations.dart @@ -96,7 +96,7 @@ Future> _loadAll(Locale locale, Iterable { /// Abstract const constructor. This constructor enables subclasses to provide /// const constructors so that they can be used in const expressions. diff --git a/packages/flutter_localizations/lib/src/l10n/README.md b/packages/flutter_localizations/lib/src/l10n/README.md index 857c687f18..4ff175ea1c 100644 --- a/packages/flutter_localizations/lib/src/l10n/README.md +++ b/packages/flutter_localizations/lib/src/l10n/README.md @@ -15,12 +15,10 @@ apps in general, see the ### Translations for one locale: .arb files The Material and Cupertino libraries use -[Application Resource Bundle](https://code.google.com/p/arb/wiki/ApplicationResourceBundleSpecification) +[Application Resource Bundle](https://github.com/google/app-resource-bundle/wiki/ApplicationResourceBundleSpecification) files, which have a `.arb` extension, to store localized translations of messages, format strings, and other values. This format is also -used by the Dart [intl](https://pub.dev/packages/intl) -package and it is supported by the -[Google Translators Toolkit](https://translate.google.com/toolkit). +used by the Dart [intl](https://pub.dev/packages/intl) package. The Material and Cupertino libraries only depend on a small subset of the ARB format. Each .arb file contains a single JSON table that diff --git a/packages/flutter_localizations/lib/src/l10n/material_en.arb b/packages/flutter_localizations/lib/src/l10n/material_en.arb index de77ae0c16..bcce0e2b39 100644 --- a/packages/flutter_localizations/lib/src/l10n/material_en.arb +++ b/packages/flutter_localizations/lib/src/l10n/material_en.arb @@ -73,7 +73,7 @@ "scrimLabel": "Scrim", "@scrimLabel": { - "description": "The label for the scrim rendered underneath the content of a modal route." + "description": "The label for the scrim rendered underneath the content of a bottom sheet (used as the 'modalRouteContentName' of the 'scrimOnTapHint' message)." }, "bottomSheetLabel": "Bottom Sheet", @@ -83,7 +83,7 @@ "scrimOnTapHint": "Close $modalRouteContentName", "@scrimOnTapHint": { - "description": "The onTapHint for the scrim rendered underneath the content of a modal route which users can tap to dismiss the content", + "description": "The onTapHint for the scrim rendered underneath the content of a modal route (especially a bottom sheet) which users can tap to dismiss the content.", "parameters": "modalRouteContentName" },