Tips and FAQ on creating localization files for @tgx_android.

0. Check out useful Telegram Translations style guide before you start.

**1.** If your language is already on the translations platform, it's good idea to join the translation process there, instead of creating a whole new localization file by yourself. Unless there's some specific reason to, of course.

2. File name must end with ".xml" or mime type set to "application/xml".

It is displayed on language settings screen, so it may be useful to include e.g. a username, where to find newer version of the localization file.

2. Files larger than 1MB are not accepted by the app. If this is an issue for your language, report to the testing group.

3. When translating plurals, refer to Unicode table's cardinal row. Find your language by code on the left, then check what strings are needed for your translation. Unused variants must be removed.

4. When translating formatted strings, refer to Translations Platform to see what's inside the arguments.

IMPORTANT STRINGS

5. language_code: used for determining pluralization rules and many other things.

See this list to find `language_code` for your language.

When installing a custom localization file, language_code is also used as an identifier, so localization files with the same language_code won't be duplicated in the list of installed languages in the app.

You can put your unique identifier (e.g. Telegam username) in language_code by using following format:

${language_code}X${your_identifier}

${language_code} still must be a valid language code
${your_identifier} must match [A-z0-9_] pattern

Examples

ru — just language code is OK (and usually better).

enXOldEnglish, ruXOldEastSlavic — this can be useful for maintaining exotic translations, since they should not be replaced by regular translations.

ruXtgx_android — if you just don't want any other translation with language_code=ru to overwrite your localization file, when user installs some other Russian localization file. This can be useful if your localization has some unique style (e.g. informal).

6. language_dateFormatLocale: locale to be used for date & time strings. If Android does not support your language, and you want date strings to be translated as well, submit report to the testing group.

Example: en-UK

7. language_name: name of the language. Displayed on Language settings screen.

Example: Русский

8. language_nameInEnglish: name of the language in English. Displayed in settings too.

Example: Russian

9. language_rtl: determines if UI has to be in the right-to-left direction. When sharing or installing RTL localization files, be aware that RTL support is not yet complete and there are many known issues.

Values: 0 (ltr) or 1 (rtl)

10. language_disable_lowercase: determines if UI has to not lowercase any string under any circumstances, i.e. because of strict grammar rules.

Values: 0 or 1

11. HOW SOME OTHER STRING IS USED?

Kindly refer to the translations platform. There are dozens of descriptions and screenshots available. Use the following URL format to find specific string: https://translations.telegram.org/en/android_x/unsorted/${string_key}.

12. WHERE TO FIND LOCALIZATION FILES?

I don't know.

13. I MADE A LOCALIZATION FILE BUT APP DOES NOT ACCEPT IT

Check out application logs in the debug menu. If this happens due to some bug, submit report to the testing group.

14. I MADE A LOCALIZATION FILE BUT CANNOT FIND MISSING STRINGS

Tap on a localization file until you see Apply Localization pop-up. Then check out application logs, it will contain the list of all strings localization is missing.

15. I MADE RTL TRANSLATION BUT APP LOOKS AWFUL

Please wait until RTL will be properly supported by the app.

There are two ways of creating a new localization without using any app except Telegram X:

1. Tap help icon in Settings - Language, then Create button.

2. Hold built-in English language, tap Create Localization.

Note that when trying to use Share as XML application may show you Invalid localization file message until you translate the Main section properly.

This section is usually auto-filled, when locale was properly set upon new file creation.

When translation is not needed, use Paste Original through three-dot menu.

Tap format arguments on the bottom to quickly insert them in the input field.

As many requested, file name requirement will be removed starting 981 version (comes later today after some other fixes will be done).

So you would be able to give any file name as you wish.

UPD: update has been uploaded to Google Play.

Starting version 982, full file name (without extension) will be displayed on the intstalled languages list.

This applies only to localization files installed on 982 or later versions.

Couple complete localization files made by amazingly quck translators on the translations platform.

Note: though 100% translated, these localizations are not guaranteed to be perfect, as they are not yet officially released.

If you find mistakes, please leave a comment on the platform.

Français / French

Exported from Telegram X

Українська / Ukrainian

Exported from Telegram X

മലയാളം / Malayalam

Exported from Telegram X

If you have any of these troubles while translating plurals:

- Missing variants (example: you need to translate "one" & "other", but only "other" variant is shown)
- Rules are applying incorrectly (example: "1 hours" instead of "1 hour")

Do following:

- Ensure you have set language_code properly
- Refer to unicode table to check how variants are used


If you believe there's an issue with the app, submit report to the testing group, including your language_code and couple sample strings.

0.21.0.984 RC

- xSecondsShort, xMinutesShort, xHoursShort, xDaysShort, xWeeksShort: used in self-destruct timers (5s, 2h, 3d, 4w, etc)
- ErrorPinnedChatsLimit: error message when trying to pin a chat with limit reached
- AskButton: "Help" alert style changed, so there'd be enough space for string (located in the main menu)
- Removed limitation of 6 lines in the in-app alerts (that appear on the bottom of the screen
- Renamed SharingLiveLocationTitle -> SharingLiveLocationToChats. Now it's plural. Needed for Polish language.
- Renamed YouCantForwardMore -> YouCantForwardMoreMessages. Now it's plural.
- SelectedAudioSuffix, SelectedFileSuffix, SelectedLinkSuffix, SelectedGifSuffix, SelectedVoiceSuffix, SelectedRoundVideoSuffix, SelectedMediaSuffix, SelectedPhotoSuffix, SelectedVideoSuffix: used when selecting items in shared media.
- ReportReasonDescription: used when reporting chat / user with "other reason" in the input field name. Needed for Chinese language.
- When opening specific string in the localization search results and going back, search results won't disappear
- When sharing cloud localizations as XML, which are not currently used, they will be synced properly
- When you have access to any -raw language, you'll be able to view status / share as XML any "Official" language (by e.g. hold)
- Improved swipe to go back on screens
- Fixed: Media picker counter is not displayed fully (affects SelectedSuffix, AttachVideosSuffix, AttachPhotosSuffix, AttachMediasSuffix)
- Fixed: Markdown in alerts is not parsed when Markdown is disabled in settings
- Fixed: "Uploading profile photo, please wait.." is not translatable in some cases when uploading profile photo: UploadingPhotoWait is now used.
- Fixed: Limited amount of lines available for empty chats list view. Affects ContactsOnTelegramOne, ContactsOnTelegramSeveral, ContactsOnTelegramMany. Now you can use as many lines as needed.
- Fixed: Tab names do not fit on Settings > Stickers screen. Affects Trending, Installed, Archived, Masks.

Also you can now translate strings used by localization tools, as requested by some translators.

Few strings missing, they will become available with the 985 update.

If you encounter Localization file is empty while trying to select Italian language, please wait until the 985 update, or reset application data and try again (but keep in mind all application data, including secret chats, will be lost).

0.21.0.985 RC

- NoChatsText: Now you need to put 2 newlines after the bold title in the beginning of the string (No chats to show in English), instead of 1. You can also use newlines by yourself freely, if needed in this string.
- When selecting a localization, which was previously used, it will be synced before the language gets applie to the UI (this fixes "Localization file is empty" for Italian language)
- Added ToolsStringSectionMain, ToolsStringSectionUrl, ToolsStringSectionFormat, ToolsStringSectionRelativeDate, ToolsStringSectionPlural, ToolsStringSectionSimpleFormatted, `ToolsStringSectionSimple: sections in localization strings list
- Added TdlibLogClearEmpty, TdlibLogClearOk, TdlibLogClearFail: toast notifications when clearing TDLib log
- Better number & file size formatting in Spanish
- Fixed: After using "Paste original" & pressing "Save & Exit", string is not saved

0.21.0.987 RC

- Changed pop-up style when adding proxies. Affects: ProxyEnable, ProxySaveForLater, EnableProxyAlertHint, EnableProxyAlertTitle

Now there's more space available for strings.

- InviteText variables now work properly.

0.21.0.988 RC

- "View Strings" for built-in language as well for translators (requires access to at least one -raw translation).
- Fixed: Invalid rule applied when selecting first item. Affects: *Suffix strings
- Added strings needed for language switch pop-up. See https://translations.telegram.org/en/android_x/new
- Added json_ChatDemo: array of Scene objects in JSON format.

Scene fields
on_date: array of integer. Optional. Format: [DAY,MONTH,YEAR,HOUR,MINUTE]. Use -1 if field value is not important. If current date or/and time matches specified value, scene will be displayed instead of default ones. Example: [7,9] or [7,9,-1] or [7,9,-1,-1,-1,-1]: Scene will be displayed on 7th September of any year.
guide: When set to 1, this scene will be displayed to translators.
member: string or User. Represents other party name.
members: array of User. Represents all members in a group chat
_: array of Message
min_version: Integer. Optional. If app version is lower than specified value, scene will be ignored. Do not set unless required, reserved for future.
max_version: Integer. Optional. If app version is higher than specified value, scene will be ignored. Do not set unless required, reserved for future.
lang: Integer. Optional. When this field is set, all string are used as localization key suffixes. Do not use unless you know what you do. Example: lang=1, text=name then json_1_name's content will be used as text content. See https://t.me/tgx_android_translate/34.

User array format
[user_id (int), first_name (string), last_name (string, optional), avatar_remote_id (string, optional)]

Message fields
out: 1 means message is outgoing.
author: Integer. Represents user_id of an author.
text: String (text) or array in format [text, enable_markdown=1]. Optional. Represents text message or caption.
audio: Array, format: [duration (int), title (string), performer (string)]. Optional.
voice: Integer (duration) or Array, format: [duration (int)].
photo: String (query) or Array, format: [query (string), width (int, optional), height (int, optional)] format.
sticker: Array, format: [width (int), height (int), thumbnail_remote_id (string), sticker_remote_id (string), set_id (long, optional)]
left: Integer (user_id). Represents left or kicked member user identifier. Group scenes only.
ttl: Integer (seconds). Amount of seconds of the new self-destruct timer. 0 means self-destruct timer has been disabled.
created: String (group title). Represents group creation message.
after: Integer (seconds). Amount of seconds after the previous message (if any). Do not set if it's not important for the scene.
date: Integer (unix timestamp). Optional exact date for the message. Do not set if it's not important for the scene. Keep in mind that the date is not displayed for the very first message (which is below "Chat Preview")

Translators, please check your languages for common typos, before your languages will get released for all users on production (which is about to happen very soon):

1. Tap "View Strings" on built-in language (English) and search for " " (single space character). See what strings start or end with a space and check if your translation has ones as well.

On older app version same could be achieved by creating an empty custom localization and pressing "View Strings" on it.

2. Tap "View Strings" on your language and check for " " (two space characters) and see if you have placed extra space anywhere.

3. Tap "View Strings" on your language and check for " " (single space character) and see if you have put extra space/newline in the beginning or the end of the line of any string (which is missing in the built-in language).

Built-in value of the json_ChatDemo.

You can use JSON minifier to minify the value after translation.

Note: app won't recommend to switch to your language until language_continueInLanguage, language_continueInLanguagePopupText, language_appliedLanguage are translated.

New default json_ChatDemo value, which is used, when it's empty (0) or contains invalid JSON.

To simplify chat demo translations, a lot of new keys have been added in 0.21.0.989.

If you don't want to change the scene and want to just translate texts / names, you can set json_ChatDemo to 0 & just translate other json_* strings.

If you have already successfuly translated json_ChatDemo, you can keep it as is and don't translate separate strings, but if you don't modify the scene itself, I'd recommend setting json_ChatDemo to 0.