Update pkg:intl README.md
Fixed code blocks
Removed gratuitous title in header
Removed dead link to Google translate toolkit
Updated outdated URLs
PiperOrigin-RevId: 334982679
diff --git a/README.md b/README.md
index ff5df07..918a48b 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,4 @@
-Intl
-====
-
-This package provides internationalization and localization facilities,
+Provides internationalization and localization facilities,
including message translation, plurals and genders, date/number formatting
and parsing, and bidirectional text.
@@ -19,13 +16,17 @@
You can explicitly set the global locale
- Intl.defaultLocale = 'pt_BR';
+```dart
+Intl.defaultLocale = 'pt_BR';
+```
or get it from the browser
- import 'package:intl/intl_browser.dart';
- ...
- findSystemLocale().then(runTheRestOfMyProgram);
+```dart
+import 'package:intl/intl_browser.dart';
+...
+findSystemLocale().then(runTheRestOfMyProgram);
+```
To override the current locale for a particular operation, pass the operation
to [withLocale][withLocale]. Note that this includes async tasks
@@ -36,7 +37,9 @@
the [withLocale][withLocale] operation may be preferable to setting
[defaultLocale][defaultLocale].
- Intl.withLocale('fr', () => print(myLocalizedMessage());
+```dart
+Intl.withLocale('fr', () => print(myLocalizedMessage());
+```
To specify the locale for an operation you can create a format object in
a specific locale, pass in the locale as a parameter to methods, or
@@ -84,13 +87,15 @@
Messages to be localized are written as functions that return the result of
an [Intl.message][Intl.message] call.
- String continueMessage() => Intl.message(
- 'Hit any key to continue',
- name: 'continueMessage',
- args: [],
- desc: 'Explains that we will not proceed further until '
- 'the user presses a key');
- print(continueMessage());
+```dart
+String continueMessage() => Intl.message(
+ 'Hit any key to continue',
+ name: 'continueMessage',
+ args: [],
+ desc: 'Explains that we will not proceed further until '
+ 'the user presses a key');
+print(continueMessage());
+```
This provides, in addition to the basic message string, a name, a description
for translators, the arguments used in the message, and examples. The `name` and
@@ -117,59 +122,67 @@
the formatting outside the function and pass the formatted string into
the message.
- greetingMessage(name) => Intl.message(
- 'Hello $name!',
- name: 'greetingMessage',
- args: [name],
- desc: 'Greet the user as they first open the application',
- examples: const {'name': 'Emily'});
- print(greetingMessage('Dan'));
+```dart
+greetingMessage(name) => Intl.message(
+ 'Hello $name!',
+ name: 'greetingMessage',
+ args: [name],
+ desc: 'Greet the user as they first open the application',
+ examples: const {'name': 'Emily'});
+print(greetingMessage('Dan'));
+```
There is one special class of complex expressions allowed in the
message string, for plurals and genders.
- remainingEmailsMessage(int howMany, String userName) =>
- Intl.message(
- '''${Intl.plural(howMany,
- zero: 'There are no emails left for $userName.',
- one: 'There is $howMany email left for $userName.',
- other: 'There are $howMany emails left for $userName.')}''',
- name: 'remainingEmailsMessage',
- args: [howMany, userName],
- desc: How many emails remain after archiving.',
- examples: const {'howMany': 42, 'userName': 'Fred'});
+```dart
+remainingEmailsMessage(int howMany, String userName) =>
+ Intl.message(
+ '''${Intl.plural(howMany,
+ zero: 'There are no emails left for $userName.',
+ one: 'There is $howMany email left for $userName.',
+ other: 'There are $howMany emails left for $userName.')}''',
+ name: 'remainingEmailsMessage',
+ args: [howMany, userName],
+ desc: How many emails remain after archiving.',
+ examples: const {'howMany': 42, 'userName': 'Fred'});
- print(remainingEmailsMessage(1, 'Fred'));
+print(remainingEmailsMessage(1, 'Fred'));
+```
However, since the typical usage for a plural or gender is for it to
be at the top-level, we can also omit the [Intl.message][Intl.message] call and
provide its parameters to the [Intl.plural][Intl.plural] call instead.
- remainingEmailsMessage(int howMany, String userName) =>
- Intl.plural(
- howMany,
- zero: 'There are no emails left for $userName.',
- one: 'There is $howMany email left for $userName.',
- other: 'There are $howMany emails left for $userName.',
- name: 'remainingEmailsMessage',
- args: [howMany, userName],
- desc: 'How many emails remain after archiving.',
- examples: const {'howMany': 42, 'userName': 'Fred'});
+```dart
+remainingEmailsMessage(int howMany, String userName) =>
+ Intl.plural(
+ howMany,
+ zero: 'There are no emails left for $userName.',
+ one: 'There is $howMany email left for $userName.',
+ other: 'There are $howMany emails left for $userName.',
+ name: 'remainingEmailsMessage',
+ args: [howMany, userName],
+ desc: 'How many emails remain after archiving.',
+ examples: const {'howMany': 42, 'userName': 'Fred'});
+```
Similarly, there is an [Intl.gender][Intl.gender] message, and plurals
and genders can be nested.
- notOnlineMessage(String userName, String userGender) =>
- Intl.gender(
- userGender,
- male: '$userName is unavailable because he is not online.',
- female: '$userName is unavailable because she is not online.',
- other: '$userName is unavailable because they are not online',
- name: 'notOnlineMessage',
- args: [userName, userGender],
- desc: 'The user is not available to hangout.',
- examples: const {{'userGender': 'male', 'userName': 'Fred'},
- {'userGender': 'female', 'userName' : 'Alice'}});
+```dart
+notOnlineMessage(String userName, String userGender) =>
+ Intl.gender(
+ userGender,
+ male: '$userName is unavailable because he is not online.',
+ female: '$userName is unavailable because she is not online.',
+ other: '$userName is unavailable because they are not online',
+ name: 'notOnlineMessage',
+ args: [userName, userGender],
+ desc: 'The user is not available to hangout.',
+ examples: const {{'userGender': 'male', 'userName': 'Fred'},
+ {'userGender': 'female', 'userName' : 'Alice'}});
+```
It's recommended to use complete sentences in the sub-messages to keep
the structure as simple as possible for the translators.
@@ -183,21 +196,21 @@
To extract messages, run the `extract_to_arb.dart` program.
- pub run intl_translation:extract_to_arb --output-dir=target/directory
- my_program.dart more_of_my_program.dart
+```console
+> pub run intl_translation:extract_to_arb --output-dir=target/directory
+ my_program.dart more_of_my_program.dart
+```
This will produce a file `intl_messages.arb` with the messages from
-all of these programs. an [ARB][ARB]
-format file which can be used for input to translation tools like
-[Google Translator Toolkit][GoogleTranslateToolkit].
+all of these programs. See [ARB][ARB].
The resulting translations can be used to generate a set of libraries
using the `generate_from_arb.dart` program.
This expects to receive a series of files, one per
locale.
-```
-pub run intl_translation:generate_from_arb --generated_file_prefix=<prefix>
+```console
+> pub run intl_translation:generate_from_arb --generated_file_prefix=<prefix>
<my_dart_files> <translated_ARB_files>
```
@@ -209,9 +222,11 @@
will automatically print the translated version instead of the
original.
- import 'my_prefix_messages_all.dart';
- ...
- initializeMessages('dk').then(printSomeMessages);
+```dart
+import 'my_prefix_messages_all.dart';
+...
+initializeMessages('dk').then(printSomeMessages);
+```
Once the future returned from the initialization call returns, the
message data is available.
@@ -220,9 +235,11 @@
To format a number, create a NumberFormat instance.
- var f = NumberFormat('###.0#', 'en_US');
- print(f.format(12.345));
- ==> 12.34
+```dart
+var f = NumberFormat('###.0#', 'en_US');
+print(f.format(12.345));
+ ==> 12.34
+```
The locale parameter is optional. If omitted, then it will use the
current locale. The format string is as described in
@@ -232,7 +249,9 @@
locale, which provides information as to the various separator
characters, patterns, and other information used for formatting, as
- f.symbols
+```dart
+f.symbols
+```
Current known limitations are that the currency format will only print
the name of the currency, and does not support currency symbols, and
@@ -246,23 +265,29 @@
taken from ICU/CLDR or using an explicit pattern. For details on the
supported skeletons and patterns see [DateFormat][DateFormat].
- DateFormat.yMMMMEEEEd().format(aDateTime);
- ==> 'Wednesday, January 10, 2012'
- DateFormat('EEEEE', 'en_US').format(aDateTime);
- ==> 'Wednesday'
- DateFormat('EEEEE', 'ln').format(aDateTime);
- ==> 'mokɔlɔ mwa mísáto'
+```dart
+DateFormat.yMMMMEEEEd().format(aDateTime);
+ ==> 'Wednesday, January 10, 2012'
+DateFormat('EEEEE', 'en_US').format(aDateTime);
+ ==> 'Wednesday'
+DateFormat('EEEEE', 'ln').format(aDateTime);
+ ==> 'mokɔlɔ mwa mísáto'
+```
You can also parse dates using the same skeletons or patterns.
- DateFormat.yMd('en_US').parse('1/10/2012');
- DateFormat('Hms', 'en_US').parse('14:23:01');
+```dart
+DateFormat.yMd('en_US').parse('1/10/2012');
+DateFormat('Hms', 'en_US').parse('14:23:01');
+```
Skeletons can be combined, the main use being to print a full date and
time, e.g.
- DateFormat.yMEd().add_jms().format(DateTime.now());
- ==> 'Thu, 5/23/2013 10:21:47 AM'
+```
+DateFormat.yMEd().add_jms().format(DateTime.now());
+ ==> 'Thu, 5/23/2013 10:21:47 AM'
+```
Known limitations: Time zones are not yet supported. Dart
[DateTime][DateTime] objects don't have a time zone, so are either
@@ -271,9 +296,11 @@
Note that before doing any DateTime formatting for a particular
locale, you must load the appropriate data by calling.
- import 'package:intl/date_symbol_data_local.dart';
- ...
- initializeDateFormatting('de_DE', null).then(formatDates);
+```dart
+import 'package:intl/date_symbol_data_local.dart';
+...
+initializeDateFormatting('de_DE', null).then(formatDates);
+```
Once the future returned from the initialization call returns, the
formatting data is available.
@@ -293,22 +320,23 @@
[RTL][BidiFormatter.RTL] and [LTR][BidiFormatter.LTR] constructors, or
detected from the text.
- BidiFormatter.RTL().wrapWithUnicode('xyz');
- BidiFormatter.RTL().wrapWithSpan('xyz');
+```dart
+BidiFormatter.RTL().wrapWithUnicode('xyz');
+BidiFormatter.RTL().wrapWithSpan('xyz');
+```
-[intl_lib]: https://www.dartdocs.org/documentation/intl/latest/intl/intl-library.html
-[Intl]: https://www.dartdocs.org/documentation/intl/latest
-[DateFormat]: https://www.dartdocs.org/documentation/intl/latest/intl/DateFormat-class.html
-[NumberFormat]: https://www.dartdocs.org/documentation/intl/latest/intl/NumberFormat-class.html
-[withLocale]: https://www.dartdocs.org/documentation/intl/latest/intl/Intl/withLocale.html
-[defaultLocale]: https://www.dartdocs.org/documentation/intl/latest/intl/Intl/defaultLocale.html
-[Intl.message]: https://www.dartdocs.org/documentation/intl/latest/intl/Intl/message.html
-[Intl_translation]: https://www.dartdocs.org/documentation/intl_translation/latest
-[Intl.plural]: https://www.dartdocs.org/documentation/intl/latest/intl/Intl/plural.html
-[Intl.gender]: https://www.dartdocs.org/documentation/intl/latest/intl/Intl/gender.html
-[DateTime]: https://api.dartlang.org/stable/dart-core/DateTime-class.html
-[BidiFormatter]: https://www.dartdocs.org/documentation/intl/latest/intl/BidiFormatter-class.html
-[BidiFormatter.RTL]: https://www.dartdocs.org/documentation/intl/latest/intl/BidiFormatter/BidiFormatter.RTL.html
-[BidiFormatter.LTR]: https://www.dartdocs.org/documentation/intl/latest/intl/BidiFormatter/BidiFormatter.LTR.html
-[ARB]: https://code.google.com/p/arb/wiki/ApplicationResourceBundleSpecification
-[GoogleTranslateToolkit]: https://translate.google.com/toolkit/
+[intl_lib]: https://pub.dev/documentation/intl/latest/intl/intl-library.html
+[Intl]: https://pub.dev/documentation/intl
+[DateFormat]: https://pub.dev/documentation/intl/latest/intl/DateFormat-class.html
+[NumberFormat]: https://pub.dev/documentation/intl/latest/intl/NumberFormat-class.html
+[withLocale]: https://pub.dev/documentation/intl/latest/intl/Intl/withLocale.html
+[defaultLocale]: https://pub.dev/documentation/intl/latest/intl/Intl/defaultLocale.html
+[Intl.message]: https://pub.dev/documentation/intl/latest/intl/Intl/message.html
+[Intl_translation]: https://pub.dev/packages/intl_translation
+[Intl.plural]: https://pub.dev/documentation/intl/latest/intl/Intl/plural.html
+[Intl.gender]: https://pub.dev/documentation/intl/latest/intl/Intl/gender.html
+[DateTime]: https://api.dart.dev/dart-core/DateTime-class.html
+[BidiFormatter]: https://pub.dev/documentation/intl/latest/intl/BidiFormatter-class.html
+[BidiFormatter.RTL]: https://pub.dev/documentation/intl/latest/intl/BidiFormatter/BidiFormatter.RTL.html
+[BidiFormatter.LTR]: https://pub.dev/documentation/intl/latest/intl/BidiFormatter/BidiFormatter.LTR.html
+[ARB]: https://github.com/google/app-resource-bundle
