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

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

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

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

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

• Поместите большую часть или все содержимое пользовательского интерфейса вашего приложения в файлы ресурсов, как описано на этой странице и в обзоре ресурсов приложения .
• С другой стороны, поведение пользовательского интерфейса определяется вашим кодом на основе Kotlin или Java. Например, если пользователи вводят данные, которые необходимо отформатировать или отсортировать по-разному в зависимости от языкового стандарта, вы используете Kotlin или язык программирования Java для программной обработки данных. На этой странице не описано, как локализовать код на основе Kotlin или Java.

Краткое руководство по локализации строк в вашем приложении см. в разделе Поддержка разных языков и культур .

Обзор: переключение ресурсов в Android

Ресурсы — это текстовые строки, макеты, звуки, графика и любые другие статические данные, необходимые вашему Android-приложению. Приложение может включать в себя несколько наборов ресурсов, каждый из которых настроен для различной конфигурации устройства. Когда пользователь запускает приложение, Android автоматически выбирает и загружает ресурсы, которые лучше всего соответствуют устройству.

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

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

Почему важны ресурсы по умолчанию

Когда приложение запускается в любой локали, для которой вы не предоставили текст, специфичный для локали, Android загружает строки по умолчанию из res/values/strings.xml . Если этот файл по умолчанию отсутствует или в нем отсутствует строка, необходимая вашему приложению, ваше приложение не запускается и отображает ошибку. Следующий пример иллюстрирует, что может произойти, если текстовый файл по умолчанию неполный.

Пример:

Код приложения на основе Kotlin или Java ссылается только на две строки: 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/layout/ : требуемый каталог, содержащий XML-файл, определяющий макет по умолчанию.
• res/anim/ : требуется, если у вас есть папки res/anim- <qualifiers>
• res/xml/ : требуется, если у вас есть папки res/xml- <qualifiers>
• res/raw/ : требуется, если у вас есть папки res/raw- <qualifiers>

Совет: В своем коде проверьте каждую ссылку на ресурс Android. Убедитесь, что для каждого из них определен ресурс по умолчанию. Также убедитесь, что файл строк по умолчанию заполнен: локализованный файл строк может содержать подмножество строк, но файл строк по умолчанию должен содержать их все.

Создайте альтернативные ресурсы

Большая часть локализации приложения — это предоставление альтернативного текста для разных языков. В некоторых случаях вы также предоставляете альтернативную графику, звуки, макеты и другие ресурсы, специфичные для локали.

Приложение может указать множество каталогов 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 или Java ссылается на 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 или Java вы ссылаетесь на ресурсы, используя синтаксис R. resource_type . resource_name или android.R. resource_type . resource_name . Дополнительные сведения см. в разделе Доступ к ресурсам вашего приложения .

Управление строками для локализации

В этом разделе описаны лучшие практики управления строками, связанными с локализацией.

Переместите все строки в strings.xml.

При создании приложений не записывайте жестко какие-либо строки. Вместо этого объявите все строки как ресурсы в файле strings.xml по умолчанию, что позволит легко их обновлять и локализовать. Строки в файле strings.xml можно легко извлечь, перевести и интегрировать обратно в ваше приложение с соответствующими квалификаторами без каких-либо изменений в скомпилированном коде.

Если вы создаете изображения с текстом, поместите эти строки также в 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/layout-de/main.xml для макета на немецком языке. Однако это может усложнить поддержку вашего приложения. Лучше создать единый макет, более гибкий.

Другая типичная ситуация — язык, который требует чего-то другого в своей компоновке. Например, у вас может быть контактная форма, которая включает два поля имени, если приложение работает на японском языке, и три поля имени, если приложение работает на каком-либо другом языке. Вы можете справиться с этим одним из двух способов:

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

Не создавайте больше файлов ресурсов и текстовых строк, чем вам нужно.

Вероятно, вам не нужно создавать альтернативу для каждого ресурса в вашем приложении, специфичную для локали. Например, макет, определенный в файле res/layout/main.xml может работать в любой локали, и в этом случае нет необходимости создавать какие-либо альтернативные файлы макета.

Кроме того, вам может не потребоваться создавать альтернативный текст для каждой строки. Например, предположим следующее:

• Язык вашего приложения по умолчанию — американский английский. Каждая строка, которую использует приложение, определяется с использованием вариантов написания американского английского языка в файле res/values/strings.xml .
• Для нескольких важных фраз вы хотите указать правописание британского английского языка. Вы хотите, чтобы эти альтернативные строки использовались при запуске вашего приложения на устройстве в Великобритании.

Для этого создайте небольшой файл с именем res/values-en-rGB/strings.xml , включающий только те строки, которые отличаются при запуске приложения в Великобритании. Для всех остальных строк приложение возвращается к значениям по умолчанию. и использует то, что определено в res/values/strings.xml .

Используйте объект контекста Android для ручного поиска локали.

Вы можете найти локаль, используя объект Context , который предоставляет Android, как показано в следующем примере:

val primaryLocale: Locale = context.resources.configuration.locales[0]
val locale: String = primaryLocale.displayName

Locale primaryLocale = context.getResources().getConfiguration().getLocales().get(0);
String locale = primaryLocale.getDisplayName();

Воспользуйтесь сервисом перевода приложения

Служба перевода приложений интегрирована в Play Console . Это позволяет вам мгновенно получить расценки и разместить заказ в переводческой компании. Вы можете заказать перевод на один или несколько языков строк пользовательского интерфейса приложения, текста листинга Play Store, названий IAP и текста рекламной кампании.

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

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

Тестирование на устройстве

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

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

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

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

Создание и использование пользовательской локали

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

• Используйте приложение Custom Locale, доступное на вкладке приложения. После создания пользовательского языкового стандарта переключитесь на него, коснувшись и удерживая имя языкового стандарта.
• Измените свой языковой стандарт в оболочке 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/ , установите испанский языковой стандарт эмулятора. Вы можете использовать приложение Custom Locale, чтобы установить для эмулятора неподдерживаемый языковой стандарт.
2. Запустите приложение.
3. Если приложение отображает сообщение об ошибке и кнопку принудительного закрытия, возможно, оно ищет недоступную строку. Убедитесь, что ваш файл res/values/strings.xml содержит определение для каждой строки, которую использует приложение.

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