Android используется на множестве устройств в разных регионах. Чтобы охватить как можно больше пользователей, убедитесь, что приложение правильно обрабатывает текст, аудиофайлы, числа, валюту и графику в соответствии с региональными стандартами.
На этой странице описаны рекомендации по локализации приложений Android.
Вам необходимо иметь практические навыки работы с Kotlin и быть знакомым с загрузкой ресурсов Android, особенностями разработки, такими как жизненный цикл объекта activity, а также общими принципами интернационализации и локализации.
Рекомендуем использовать фреймворк ресурсов Android, чтобы максимально отделить локализованные элементы приложения от его основных функций.
- Поместите большую часть или все содержимое пользовательского интерфейса приложения в файлы ресурсов, как описано на этой странице и в обзоре ресурсов приложения.
- Поведение интерфейса определяется кодом на Kotlin. Например, если пользователи вводят данные, которые нужно отформатировать или отсортировать по-разному в зависимости от региона, вы можете использовать Kotlin для программной обработки данных. На этой странице не рассказывается, как локализовать код на Kotlin.
В этом руководстве описана основная система локализации Android, которая используется во всех приложениях Android. Чтобы узнать, как загружать локализованные ресурсы в интерфейс Jetpack Compose, ознакомьтесь с разделом Ресурсы в Compose.
Краткое руководство по локализации строк в приложении можно найти в разделе Поддержка разных языков и культур.
Обзор: переключение ресурсов в Android
Ресурсы – это текстовые строки, звуки, изображения и любые другие статические данные, необходимые приложению Android. Приложение может содержать несколько наборов ресурсов, каждый из которых предназначен для определенной конфигурации устройства. Когда пользователь запускает приложение, Android автоматически выбирает и загружает ресурсы, которые лучше всего подходят для устройства.
На этой странице рассматриваются локализация и языковой стандарт. Полное описание переключения ресурсов и всех типов конфигураций, которые можно указать, например ориентации экрана или типа сенсорного экрана, приведено в разделе Предоставление альтернативных ресурсов.
При создании приложения вы можете добавить в него ресурсы по умолчанию и альтернативные ресурсы. Когда пользователи запускают ваше приложение, система Android выбирает, какие ресурсы загрузить, на основе региональных настроек устройства.
Чтобы создать ресурсы, поместите файлы в подкаталоги с определенными названиями в каталоге res/ проекта.
Почему важны ресурсы по умолчанию
Если приложение запущено в регионе, для которого вы не предоставили текст, Android загружает строки по умолчанию из файла res/values/strings.xml. Если файл по умолчанию отсутствует или в нем нет строки, необходимой приложению, оно не запустится и покажет ошибку. В приведенном ниже примере показано, что может произойти, если текстовый файл по умолчанию неполный.
Пример
В коде приложения на Kotlin используются только две строки: text_a и text_b. В приложении есть локализованный файл ресурсов (res/values-en/strings.xml), в котором на английском языке определены атрибуты text_a и text_b.
В приложении также есть файл ресурсов по умолчанию (res/values/strings.xml), в котором есть определение для text_a, но нет определения для text_b.
- Если запустить это приложение на устройстве, где в качестве языка выбран английский, оно может работать без проблем, поскольку в файле
res/values-en/strings.xmlесть обе необходимые текстовые строки. - Однако при запуске этого приложения на устройстве, где выбран другой язык, пользователь увидит сообщение об ошибке и кнопку "Принудительно закрыть". Приложение не загружается.
Чтобы избежать такой ситуации, убедитесь, что файл res/values/strings.xml существует и в нем определены все необходимые строки. Это относится ко всем типам ресурсов, а не только к строкам. Вам нужно создать набор файлов ресурсов по умолчанию, содержащих все ресурсы, которые использует ваше приложение, например изображения, шрифты или цвета. Информацию о тестировании можно найти в разделе Проверка ресурсов по умолчанию.
Как использовать ресурсы для локализации
В этом разделе рассказывается, как создавать ресурсы по умолчанию и альтернативные ресурсы. Также в ней рассказывается, как ресурсам назначается приоритет и как ссылаться на ресурсы в коде.
Как создать ресурсы по умолчанию
Вставьте текст по умолчанию из приложения в res/values/strings.xml. Для этих строк используйте язык по умолчанию – тот, на котором говорит большинство пользователей вашего приложения.
Набор ресурсов по умолчанию также включает все изображения по умолчанию и может содержать другие типы ресурсов, например значки или строки. Эти ресурсы должны находиться в следующих каталогах:
res/drawable/– обязательный каталог, в котором должен быть хотя бы один графический файл для значка приложения в Google Play.res/xml/: требуется, если у вас есть папкиres/xml-<qualifiers>.res/raw/: требуется, если у вас есть папкиres/raw-<qualifiers>.
Как создать альтернативные ресурсы
Важная часть локализации приложения – это добавление альтернативного текста на разных языках. В некоторых случаях вы также предоставляете альтернативные изображения, звуки и другие ресурсы, предназначенные для определенных языков.
Приложение может указать несколько каталогов res/<qualifiers>/, каждый со своими квалификаторами. Чтобы создать альтернативный ресурс для другой локали, используйте квалификатор, который указывает язык или сочетание языка и региона. Название каталога ресурсов должно соответствовать схеме именования, описанной в разделе Предоставление альтернативных ресурсов, иначе приложение не будет скомпилировано.
Пример
Предположим, что язык приложения по умолчанию – английский и вы хотите перевести весь текст в приложении на французский, а весь текст, кроме названия, – на японский. В этом случае вы создадите три файла strings.xml, каждый из которых будет храниться в каталоге ресурсов, относящемся к определенной локали:
res/values/strings.xml
Содержит текст на английском языке для всех строк, используемых в приложении, в том числе для строки с названиемtitle.res/values-fr/strings.xml
Содержит французский текст для всех строк, включаяtitle.res/values-ja/strings.xml
Содержит японский текст для всех строк, кромеtitle.
Если в вашем коде на Kotlin есть ссылка на R.string.title, во время выполнения произойдет следующее:
- Если на устройстве выбран любой другой язык, Android загружает
titleиз файлаres/values/strings.xml. - Если на устройстве выбран французский язык, Android загрузит
titleиз файлаres/values-fr/strings.xml.
Если на устройстве выбран японский язык, Android будет искать title в файле res/values-ja/strings.xml. Но поскольку в этом файле нет такой строки, Android возвращается к значению по умолчанию и загружает title на английском языке из файла res/values/strings.xml.
Какие ресурсы имеют приоритет?
Если конфигурации устройства соответствуют несколько файлов ресурсов, Android выбирает один из них по определенным правилам. Среди квалификаторов, которые можно указать в названии каталога ресурсов, локаль почти всегда имеет приоритет.
Пример
Предположим, что в приложении есть набор графических объектов по умолчанию и два других набора, каждый из которых оптимизирован для определенной конфигурации устройства:
res/drawable/
Содержит графические объекты по умолчанию.res/drawable-small-land-stylus/
Содержит графику, оптимизированную для использования на устройстве, которое поддерживает ввод с помощью стилуса и имеет QVGA-экран с низкой плотностью пикселей в альбомной ориентации.res/drawable-ja/
Содержит графику, оптимизированную для использования с японским языком.
Если приложение запущено на устройстве, для которого задан японский язык, Android загружает графику из res/drawable-ja/, даже если устройство поддерживает ввод с помощью стилуса и имеет QVGA-экран с низкой плотностью пикселей в горизонтальной ориентации.
Исключение. Единственные квалификаторы, которые имеют приоритет над языком в процессе выбора, – это код страны мобильной связи (MCC) и код мобильной сети (MNC).
Пример
Предположим, что у вас возникла следующая ситуация:
- Код приложения вызывает
R.string.text_a. - Доступны два файла ресурсов:
res/values-mcc404/strings.xml, в том числеtext_aна языке приложения по умолчанию, в данном случае на английском.res/values-hi/strings.xml, в том числеtext_aна хинди.
- Приложение запущено на устройстве со следующей конфигурацией:
- SIM-карта подключена к мобильной сети в Индии (MCC 404).
- Язык установлен на хинди (
hi).
Android загружает text_a из res/values-mcc404/strings.xml (на английском языке), даже если на устройстве выбран хинди. Это связано с тем, что при выборе ресурсов Android отдает предпочтение совпадению MCC, а не языка.
Процесс выбора не всегда так прост, как в этих примерах. Более подробное описание этого процесса приведено в статье Как Android находит наиболее подходящий ресурс. Все квалификаторы описаны и перечислены в порядке приоритета в обзоре ресурсов приложения.
Как ссылаться на ресурсы в коде
В коде приложения на языке Kotlin вы обращаетесь к ресурсам, используя синтаксис R.resource_type.resource_name или android.R.resource_type.resource_name.
Подробнее о том, как получить доступ к ресурсам приложения…
Как управлять строками для локализации
В этом разделе описаны рекомендации по управлению строками, связанными с локализацией.
Переместить все строки в strings.xml
При создании приложений не используйте строки с жестким кодированием. Вместо этого объявите все строки как ресурсы в файле strings.xml по умолчанию, чтобы их было легко обновлять и локализовать. Строки из файла strings.xml можно легко извлечь, перевести и добавить обратно в приложение с подходящими квалификаторами, не меняя скомпилированный код.
Например, в Compose можно загрузить строку следующим образом:
// In the res/values/strings.xml file // <string name="compose">Jetpack Compose</string> // In your Compose code Text( text = stringResource(R.string.compose) )
Если вы создаете изображения с текстом, добавьте эти строки в strings.xml и сгенерируйте изображения заново после перевода.
Соблюдайте правила Android для строк интерфейса
При разработке интерфейса обращайте особое внимание на то, как вы обращаетесь к пользователю. В целом рекомендуется использовать краткий и дружелюбный стиль, а также придерживаться его во всех интерфейсах.
Ознакомьтесь с рекомендациями по стилю и выбору слов в Material Design. Это сделает ваши приложения более привлекательными для пользователей и поможет им быстрее разобраться в интерфейсе.
Кроме того, по возможности всегда используйте стандартную терминологию Android, например для элементов интерфейса, таких как панель приложений, меню параметров, системная строка и уведомления. Правильное и единообразное использование терминов Android упрощает перевод и позволяет создавать более качественные продукты для пользователей.
Предоставляйте достаточно контекста для объявленных строк
При объявлении строк в файле strings.xml обязательно указывайте контекст, в котором они используются. Эта информация очень важна для переводчика и позволяет повысить качество перевода. а также более эффективно управлять строками.
Пример:
<!-- The action for submitting a form. This text is on a button that can fit 30 chars --> <string name="login_submit_button">Sign in</string>
Попробуйте добавить контекстную информацию, например:
- Для чего нужна эта строка? Когда и где оно показывается пользователю?
- Где это в интерфейсе? Например, перевод текста на кнопках менее гибкий, чем перевод текста в текстовых полях.
Как отметить части письма, которые не нужно переводить
Часто строки содержат текст, который не нужно переводить на другие языки. Чаще всего это фрагмент кода, плейсхолдер для значения, специальный символ или название. Подготавливая строки к переводу, найдите и отметьте текст, который должен остаться без изменений, чтобы переводчик не перевел его.
Чтобы отметить текст, который не нужно переводить, используйте тег-заполнитель <xliff:g>.
Вот пример тега, который указывает, что текст "%1$s" не нужно изменять при переводе, чтобы не нарушить смысл сообщения:
<string name="countdown"> <xliff:g id="time" example="5 days">%1$s</xliff:g> until holiday </string>
При объявлении тега плейсхолдера добавьте атрибут ID, который объясняет, для чего нужен плейсхолдер. Если в приложении значение плейсхолдера будет заменено, обязательно добавьте пример атрибута, чтобы пояснить, как его использовать.
Вот ещё несколько примеров тегов-заполнителей:
<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2"> <!-- Example placeholder for a special Unicode symbol --> <string name="star_rating">Check out our 5 <xliff:g id="star">\u2605</xliff:g> </string> <!-- Example placeholder for a URL --> <string name="app_homeurl"> Visit us at <xliff:g id="application_homepage">http://my/app/home.html</xliff:g> </string> <!-- Example placeholder for a name --> <string name="prod_name"> Learn more at <xliff:g id="prod_gamegroup">Game Group</xliff:g> </string> <!-- Example placeholder for a literal --> <string name="promo_message"> Please use the "<xliff:g id="promotion_code">ABCDEFG</xliff:g>" to get a discount. </string> ... </resources>
Контрольный список по локализации
Подробнее о том, как перевести и локализовать приложение для Android…
Советы по локализации
При локализации приложения следуйте приведенным ниже советам.
Как сделать приложение доступным в разных странах
Не делайте никаких предположений об устройстве, на котором пользователь запускает ваше приложение. У него может быть оборудование, которое вы не учитывали, или оно может быть настроено на язык, который вы не планировали или не можете протестировать. Приложение должно работать корректно или корректно завершать работу на любом устройстве.
Важно! Убедитесь, что в приложении есть полный набор ресурсов по умолчанию: папки res/drawable/ и res/values/ без дополнительных модификаторов в названиях, содержащие все изображения и текст, необходимые приложению.
Если в приложении отсутствует хотя бы один ресурс по умолчанию, оно не будет работать на устройстве, для которого задана неподдерживаемая локаль. Например, если в файле res/values/strings.xml по умолчанию отсутствует строка, необходимая приложению, то при запуске приложения в неподдерживаемой локали и попытке загрузить res/values/strings.xml пользователь увидит сообщение об ошибке и кнопку "Закрыть приложение".
Подробнее о тестировании ресурсов по умолчанию…
Не создавайте лишние файлы ресурсов и текстовые строки
Вам, вероятно, не нужно создавать альтернативные версии для каждого ресурса в приложении. Например, логотип приложения, определенный в каталоге res/drawable/, может подходить для любого языка, и в этом случае нет необходимости создавать альтернативные графические файлы.
Кроме того, не для каждой строки нужно создавать альтернативный текст. Например, предположим следующее:
- В приложении по умолчанию используется американский английский. Все строки, используемые в приложении, определены в файле
res/values/strings.xmlс использованием американского английского. - Для нескольких важных фраз вы хотите использовать британский вариант написания. Вы хотите, чтобы эти строки использовались, когда приложение запускается на устройстве в Великобритании.
Для этого создайте небольшой файл res/values-en-rGB/strings.xml, в котором будут только строки, отличающиеся при запуске приложения в Великобритании. Для всех остальных строк приложение будет использовать значения по умолчанию, определенные в файле res/values/strings.xml.
Как использовать LocalConfiguration для поиска локали вручную
Вы можете найти локаль, используя LocalConfiguration, доступный в Android, как показано в следующем примере:
val locale = LocalConfiguration.current.locales[0]
Чтобы заказать профессиональный
Сервис "Локализация приложений" интегрирован в Play Console. Он позволяет мгновенно получить предложение и разместить заказ в компании, занимающейся переводами. Вы можете заказать перевод на один или несколько языков строк интерфейса приложения, текста страницы приложения в Google Play, названий контента для продажи и текста рекламной кампании.
Как переводить строки приложения с помощью Gemini
Вы можете использовать Gemini в Android Studio, чтобы переводить строковые ресурсы приложения прямо в проекте. Подробнее о том, как локализовать приложение…
Как тестировать локализованные приложения
Протестируйте локализованное приложение на устройстве или с помощью эмулятора Android. В частности, проверьте, включены ли в приложение все необходимые ресурсы по умолчанию.
Как протестировать на устройстве
Помните, что устройство, на котором вы проводите тестирование, может значительно отличаться от устройств, доступных потребителям в других регионах. На разных устройствах могут быть доступны разные языки. Кроме того, разрешение и плотность экрана устройства могут различаться, что может повлиять на отображение строк и объектов в вашем интерфейсе.
Чтобы изменить язык или региональные настройки на устройстве, используйте приложение "Настройки".
Тестирование с помощью комбинируемых предварительных просмотров
Перед тестированием на устройстве вы можете использовать composable-функции для предварительного просмотра в Android Studio, чтобы проверить локализованные интерфейсы без развертывания в эмуляторе. Чтобы посмотреть, как будет выглядеть интерфейс на разных языках, используйте аннотацию @Preview (например, @Preview(locale = "fr")). Вы также можете протестировать макеты с направлением письма справа налево, указав соответствующую локаль, например @Preview(locale = "ar").
Как протестировать приложение в эмуляторе
Подробнее о том, как запускать приложения в эмуляторе Android…
Как создать и использовать специальную локаль
Особые региональные настройки – это сочетание языка и региона, которое не поддерживается образом системы Android. Вы можете проверить, как ваше приложение работает в определенной стране или регионе, создав в эмуляторе пользовательскую локаль. Это можно сделать двумя способами:
- Используйте приложение Custom Locale, доступное на вкладке приложений. После создания специальной локали переключитесь на нее, нажав на название локали и удерживая его.
- Переключиться на специальную локаль из оболочки
adb, как описано в следующем разделе.
Если в эмуляторе задана локаль, которая недоступна в образе системы Android, система будет отображаться на языке по умолчанию. Однако ваше приложение локализовано правильно.
Как изменить язык эмулятора с помощью оболочки ADB
Чтобы изменить локаль в эмуляторе с помощью оболочки adb, выполните следующие действия:
- Выберите нужный регион и определите его языковой тег BCP-47, например
fr-CAдля канадского французского. - Запустите эмулятор.
- В командной оболочке на хост-компьютере выполните следующую команду:
adb shell
Если у вас подключено устройство, укажите, что вы хотите использовать эмулятор, добавив параметр-e:
adb -e shell - В командной строке
adb(#) выполните следующую команду:
setprop persist.sys.locale [BCP-47 language tag];stop;sleep 5;start
Вместо элементов, заключенных в скобки, подставьте коды, полученные на шаге 1.
Например, чтобы протестировать канадский французский язык, выполните следующие действия:
setprop persist.sys.locale fr-CA;stop;sleep 5;start
Эмулятор будет перезапущен. Когда главный экран снова появится, запустите приложение. Оно откроется с новым языком.
Тестирование ресурсов по умолчанию
Чтобы проверить, есть ли в приложении все необходимые строковые ресурсы, выполните следующие действия:
- Установите в эмуляторе или на устройстве язык, который не поддерживается в вашем приложении. Например, если в приложении есть строки на французском языке в файле
res/values-fr/, но нет строк на испанском языке в файлеres/values-es/, задайте в эмуляторе испанский язык. В приложении Custom Locale можно задать для эмулятора неподдерживаемую локаль. - Запустите приложение.
- Если в приложении появляется сообщение об ошибке и кнопка "Закрыть принудительно", возможно, оно ищет строку, которая недоступна. Убедитесь, что в файле
res/values/strings.xmlесть определения для всех строк, которые используются в приложении.
Если проверка прошла успешно, повторите ее для других типов конфигураций. Например, если в приложении есть файл со строками res/values-land/strings.xml, но нет файла res/values-port/strings.xml, установите на эмуляторе или устройстве книжную ориентацию и проверьте, запустится ли приложение.
Дополнительные ресурсы
Дополнительную информацию о локализации можно найти в следующих ресурсах: