g11n, i18n, l10n... или один из множества вариантов локализации приложения. Привет, меня зовут Константин Комков и я надеюсь данный пример и последовательность шагов сэкономят Вам время при разработке!
Есть два способа хранить локализованные данные — внутри приложения или запрашивать их с сервера. Второй подход сложнее и трудозатратнее, но дает следующее преимущество — возможность заменить ресурс или исправить ошибку в переводе без новой сборки приложения. В этой статье я опишу логику работы приложения если данные приходят с сервера.
Исходные данные
-
Для локализации необходимо знать список языков и список переводов фраз. Данные придут с сервера, значит, интерфейс приложения должен обновится после выполнения запросов.
-
В этой статье я рассматриваю пример, когда данные загружаются не сразу, а после выполнения какой‑либо бизнес логики — это чуть усложняет пример.
Шаги реализации
-
Необходимо предусмотреть локаль по умолчанию и ресурсы (переводы для этой локали) должны быть в коде приложения. До того как сервер пришлет переводы — показываем данные которые зашиты в приложение. Можно добавить в приложение переводы для всех используемых языков, но следует помнить, что эти файлы нужно будет поддерживать в актуальном состоянии — достаточно одного или двух языков. Все запросы к API должны предусматривать передачу флага для выбранной локали, чтобы приходили локализованные данные.
-
После получения данных с сервера — кешируем их. При повторном запуске приложения переводы должны быть взяты из кеша, т.к. данные в кеше уже более новые чем, записанные в приложение при сборке.
Тонкости реализации кеширования данных: если запустить приложение в котором есть новые ключи, приложение получит данные из кеша, а переводов для новых ключей не будет.
-
Необходимо добавить логику определения версии приложения — новая или старая, для этого будем получать текущую версию приложения и после сравнения её с версией из кеша, записывать в кеш. Если версия новая переводы получаем из кода приложения, иначе из кеша.
-
При добавлении новых фраз, языков всегда нужно поднимать версию приложения. Для IOS приложений следует помнить что список поддерживаемых языков указывается в файле info.plist.
-
После получения данных с сервера необходимо обновить интерфейс приложения — для обновления текста.
Последовательность действий
-
Создать модели для локализуемых объектов. Для локализации текста создаем ключ для фразы, а потом находим значение для этого ключа в соответствии с выбранной локалью.
Не используйте сущность для модели содержащей ключи и переводы - у Вас и так будет много мест где нужно вносить изменения при добавлении в приложение новой фразы - (Keep it simple stupid). Ключи для переводимых фраз лучше группировать по страницам pageNamePhrasePart, часто встречающиеся слова лучше записывать без названий страниц.
-
По Clean Architecture создать внешнее и локальное хранилище данных для локализации.
-
Создать репозиторий для локализации.
-
Создать сервисы: сохранения данных в кеш, локализации, информации о версии приложения.
-
Добавить в проект библиотеку easy localization.
Мне больше нравится библиотека intl, но так сложилось, что «виновником» появления статьи является easy localization.
-
Написать свой AssetLoader — AssetCacheRemoteLoader, т.к. у нас не простая логика, а подходящего загрузчика в списке доступных нет.
-
Реализовать обновление интерфейса, в данном случае я использовал ValueListenableBuilder, но можно использовать и любой state manager.
-
Запустить процесс получения данных с сервера в нужном вам месте приложения и обновить EasyLocalizationProvider.
В этой последовательности действий нет ничего сложного, но пункты 6 и 8 могут вызвать затруднения поэтому приведу здесь пример реализации.
asset_cache_remote_loader.dart
import 'dart:async';
import 'dart:ui';
import 'package:easy_localization/easy_localization.dart';
import 'package:server_side_localization/features/localization/data/models/supported_translations.dart';
import 'package:server_side_localization/features/localization/data/models/translations.dart';
import 'package:server_side_localization/features/localization/domain/repositories/localization_cache_repository.dart';
import 'package:server_side_localization/generated/codegen_loader.g.dart';
import 'package:server_side_localization/services/package_info/package_info_service.dart';
class AssetCacheRemoteLoader extends RootBundleAssetLoader {
static final AssetCacheRemoteLoader _singleton =
AssetCacheRemoteLoader._internal();
factory AssetCacheRemoteLoader() => _singleton;
AssetCacheRemoteLoader._internal();
bool isFirstLoading = true;
SupportedTranslations? translations;
@override
Future<Map<String, dynamic>?> load(String path, Locale locale) async {
if (translations != null) {
final value = translations!.toJson()[locale.languageCode];
if (value is Translations) {
return value.toJson();
}
return CodegenLoader.mapLocales.containsKey(locale.languageCode)
? CodegenLoader.mapLocales[locale.languageCode]
: CodegenLoader.mapLocales['en'];
}
final (
localData,
isAnotherVersion,
) = await (
LocalizationCacheRepositoryImpl().getSupportedLocale(locale.languageCode),
PackageInfoService().isAnotherVersion(),
).wait;
if (isAnotherVersion && isFirstLoading) {
isFirstLoading = false;
final currentLocale =
CodegenLoader.mapLocales.containsKey(locale.languageCode)
? locale
: Locale('en');
return CodegenLoader.mapLocales[currentLocale.languageCode];
}
return localData == null
? CodegenLoader.mapLocales[locale.languageCode]
: localData.toJson();
}
}Функция обновления локализуемых данных в easy localization
Future<void> _resetTranslations({
required SupportedTranslations translations,
required List<LanguageEntity> languages,
}) async {
final provider = EasyLocalization.of(context);
AssetCacheRemoteLoader().translations = translations;
if (LocalizationService().locale != null && provider != null) {
await provider.delegate.localizationController?.loadTranslations();
await provider.delegate.load(LocalizationService().locale!);
LocalizationService().setLanguages(languages);
}
}Автор: KonstantinKomkov
