|
| 1 | +# Translations |
| 2 | + |
| 3 | +Our goal is for this app to be localized and offered in many |
| 4 | +languages, just like zulip-mobile and zulip web. |
| 5 | + |
| 6 | +## Current state |
| 7 | + |
| 8 | +Currently in place is integration with `flutter_localizations` |
| 9 | +package, allowing all flutter UI elements to be localized |
| 10 | + |
| 11 | +Per the discussion in #275 the approach here is to start with |
| 12 | +ARB files and have dart autogenerate the bindings. I believe |
| 13 | +this is the most straightforward way when connecting with a |
| 14 | +translation management system, as they output ARB files that |
| 15 | +we consume (this is also the same way web and mobile works |
| 16 | +but with .po or .json files, I believe). |
| 17 | + |
| 18 | +## Adding new strings |
| 19 | + |
| 20 | +Add the appropriate entry in `assets/l10n/app_en.arb` ensuring |
| 21 | +you add a corresponding resource attribute describing the |
| 22 | +string in context. Example: |
| 23 | + |
| 24 | +``` |
| 25 | + "profileButtonSendDirectMessage": "Send direct message", |
| 26 | + "@profileButtonSendDirectMessage": { |
| 27 | + "description": "Label for button in profile screen to navigate to DMs with the shown user." |
| 28 | + }, |
| 29 | +``` |
| 30 | + |
| 31 | +The bindings are automatically generated when you execute |
| 32 | +`flutter run` although you can also manually trigger it |
| 33 | +using `flutter gen-l10n`. |
| 34 | + |
| 35 | +Untranslated strings will be included in a generated |
| 36 | +`build/untranslated_messages.json` file. This output |
| 37 | +awaits #276. |
| 38 | + |
| 39 | +## Using in code |
| 40 | + |
| 41 | +To utilize in our widgets you need to import the generated |
| 42 | +bindings: |
| 43 | +``` |
| 44 | +import 'package:flutter_gen/gen_l10n/zulip_localizations.dart'; |
| 45 | +``` |
| 46 | + |
| 47 | +And in your widget code pull the localizations out of the context: |
| 48 | +``` |
| 49 | +Widget build(BuildContext context) { |
| 50 | + final zulipLocalizations = ZulipLocalizations.of(context); |
| 51 | +``` |
| 52 | + |
| 53 | +And finally access one of the generated properties: |
| 54 | +`Text(zulipLocalizations.chooseAccountButtonAddAnAccount)`. |
| 55 | + |
| 56 | +String that take placeholders are generated as functions |
| 57 | +that take arguments: `zulipLocalizations.subscribedToNStreams(store.subscriptions.length)` |
| 58 | + |
| 59 | +## Hack to enforce locale (for testing, etc) |
| 60 | + |
| 61 | +To manually trigger a locale change for testing I've found |
| 62 | +it helpful to add the `localeResolutionCallback` in |
| 63 | +`app.dart` to enforce a particular locale: |
| 64 | + |
| 65 | +``` |
| 66 | +return GlobalStoreWidget( |
| 67 | + child: MaterialApp( |
| 68 | + title: 'Zulip', |
| 69 | + localizationsDelegates: ZulipLocalizations.localizationsDelegates, |
| 70 | + supportedLocales: ZulipLocalizations.supportedLocales, |
| 71 | + localeResolutionCallback: (locale, supportedLocales) { |
| 72 | + return const Locale("ja"); |
| 73 | + }, |
| 74 | + theme: theme, |
| 75 | + home: const ChooseAccountPage())); |
| 76 | +``` |
| 77 | + |
| 78 | +(careful that returning a locale not in `supportedLocales` |
| 79 | +will crash, the default behavior ensures a fallback is |
| 80 | +always selected) |
| 81 | + |
| 82 | +## Tests |
| 83 | + |
| 84 | +Widgets that access localization will fail if the root |
| 85 | +`MaterialApp` given in the setup isn't also set up with |
| 86 | +localizations. Make sure to add the right |
| 87 | +`localizationDelegates` and `supportedLocales`: |
| 88 | + |
| 89 | +``` |
| 90 | + await tester.pumpWidget( |
| 91 | + GlobalStoreWidget( |
| 92 | + child: MaterialApp( |
| 93 | + navigatorObservers: navigatorObserver != null ? [navigatorObserver] : [], |
| 94 | + localizationsDelegates: ZulipLocalizations.localizationsDelegates, |
| 95 | + supportedLocales: ZulipLocalizations.supportedLocales, |
| 96 | + home: PerAccountStoreWidget( |
| 97 | +``` |
0 commit comments