Локализуйте свое приложение

Android работает на множестве устройств в разных регионах. Чтобы охватить как можно больше пользователей, убедитесь, что ваше приложение обрабатывает текст, аудиофайлы, числа, валюту и графику способами, соответствующими языковым особенностям регионов, где оно используется.

На этой странице описаны лучшие практики локализации приложений для Android.

Вам необходимо иметь практические знания Kotlin, а также быть знакомым с загрузкой ресурсов в Android , особенностями разработки, такими как жизненный цикл активности , и общими принципами интернационализации и локализации.

Рекомендуется использовать фреймворк ресурсов 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 , каждый из которых будет храниться в каталоге ресурсов, специфичном для вашей локали:

1. res/values/strings.xml
   Содержит текст на английском языке для всех строк, используемых приложением, включая текст для строки с именем title .
2. res/values-fr/strings.xml
   Содержит французский текст для всех строк, включая title .
3. 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 следует набору правил при выборе файла для использования. Среди параметров, которые можно указать в имени каталога ресурсов, параметр locale почти всегда имеет приоритет.

Пример:

Предположим, что приложение включает в себя стандартный набор графических элементов и два других набора, каждый из которых оптимизирован для различных настроек устройства:

• 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)
)
ResourcesSnippets.kt

Если вы создаете изображения с текстом, добавьте эти строки также в 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 . Он позволяет мгновенно получить предварительную оценку стоимости и разместить заказ в компании, занимающейся переводом. Вы можете заказать перевод на один или несколько языков для строк пользовательского интерфейса приложения, текста в описании приложения в Play Store, названий внутриигровых покупок и текста рекламных кампаний.

Используйте Gemini для перевода строк приложения.

В Android Studio вы можете использовать Gemini для перевода строковых ресурсов вашего приложения непосредственно в проекте. Для получения дополнительной информации см. раздел «Перевод и локализация приложения» .

Тестируйте локализованные приложения

Протестируйте локализованное приложение на устройстве или с помощью эмулятора Android. В частности, протестируйте приложение, чтобы убедиться, что все необходимые ресурсы по умолчанию включены.

Проверка на устройстве

Учтите, что устройство, на котором вы проводите тестирование, может значительно отличаться от устройств, доступных потребителям в других странах. Доступные на вашем устройстве языковые настройки могут отличаться от тех, что доступны на других устройствах. Кроме того, разрешение и плотность экрана устройства могут отличаться, что может повлиять на отображение строк и графических элементов в вашем пользовательском интерфейсе.

Чтобы изменить язык или язык на устройстве, воспользуйтесь приложением «Настройки».

Тестирование с возможностью создания предварительных просмотров

Перед тестированием на устройстве вы можете использовать компонуемые предварительные просмотры в Android Studio для проверки локализованных пользовательских интерфейсов без развертывания на эмуляторе. Для предварительного просмотра пользовательского интерфейса на разных языках используйте аннотацию @Preview (например, @Preview(locale = "fr") ). Вы также можете тестировать макеты с направлением письма справа налево (RTL), указав локаль RTL, например, @Preview(locale = "ar") .

Протестируйте на эмуляторе.

Подробную информацию об использовании эмулятора см. в разделе «Запуск приложений в эмуляторе Android» .

Создайте и используйте пользовательскую локаль.

Пользовательская локаль — это комбинация языка и региона, которую образ системы Android явно не поддерживает. Вы можете проверить, как ваше приложение работает в пользовательской локали, создав её в эмуляторе. Это можно сделать двумя способами:

• Воспользуйтесь приложением «Настройка языковых настроек», которое доступно на вкладке приложений. После создания пользовательской языковой настройки переключитесь на неё, нажав и удерживая название языковой настройки.
• Переключитесь на пользовательскую локаль в оболочке adb , как описано в следующем разделе.

Если установить для эмулятора языковую локаль, недоступную в образе системы Android, система будет отображаться на языке по умолчанию. Однако ваше приложение локализуется корректно.

Изменить языковые настройки эмулятора можно через оболочку adb.

Чтобы изменить язык в эмуляторе с помощью оболочки adb , выполните следующие действия:

1. Выберите языковой стандарт, который хотите протестировать, и определите его языковой тег BCP-47, например, fr-CA для канадского французского.
2. Запустите эмулятор.
3. В командной строке на хост-компьютере выполните следующую команду:
   adb shell
   или, если у вас подключено устройство, укажите, что вы хотите использовать эмулятор, добавив опцию -e :
   adb -e shell
4. В командной строке adb ( # ) выполните следующую команду:
   setprop persist.sys.locale [ BCP-47 language tag ];stop;sleep 5;start
   Замените разделы в скобках соответствующими кодами из Шага 1.
   
   Например, для проверки знаний на канадском французском языке:
   setprop persist.sys.locale fr-CA;stop;sleep 5;start

Это приведет к перезапуску эмулятора. Как только снова появится главный экран, перезапустите приложение, и оно запустится с новыми языковыми настройками.

Проверка наличия ресурсов по умолчанию.

Чтобы проверить, включает ли приложение все необходимые ему строковые ресурсы, выполните следующие действия:

1. Установите для эмулятора или устройства язык, который не поддерживается вашим приложением. Например, если в res/values-fr/ есть французские строки, а в res/values-es/ нет испанских, установите для эмулятора испанский язык. Для этого можно использовать приложение «Настройка локали».
2. Запустите приложение.
3. Если приложение отображает сообщение об ошибке и кнопку «Принудительное закрытие», возможно, оно ищет недоступную строку. Убедитесь, что в файле res/values/strings.xml содержится определение для каждой строки, используемой приложением.

Если тест пройден успешно, повторите его для других типов конфигураций. Например, если в приложении есть строковый файл res/values-land/strings.xml , но отсутствует файл res/values-port/strings.xml , то установите эмулятор или устройство в портретную ориентацию и проверьте, запускается ли приложение.

Дополнительные ресурсы

Для получения дополнительной информации о локализации см. следующие дополнительные ресурсы:

Документация

• Обзор ресурсов приложения
• Переведите и локализуйте ваше приложение.

Просмотры контента

• Локализуйте ваше приложение (Views)