Creating a custom language in Telegram on Android: a complete guide with examples

Telegram is one of the few messengers that allows not only change design themes, but also completely translate the interface into any languageincluding fictitious or dialect variants. This feature is especially popular among enthusiasts who want to tailor the application to regional features, meme communities, or even personal jokes. However, the official documentation for creating language packs is scattered across different sources, and the process requires working with JSON files and Bot API.

In this guide we will cover all the way from preparing a translation template to loading a custom language in Telegram on Android. You'll learn what tools you'll need, how to avoid common mistakes when validating files, and why some strings may not appear in the interface. We will also show you how to test the translation before publication, so as not to encounter problems like "Invalid language pack".

Important: the process of creating a language does not require root access or APK modification, but will require basic skills in working with text files and APIs. If you have never encountered JSON or the command line, don’t worry, we will go through each step in detail.

What are language packs in Telegram and how do they work

Telegram uses decentralized translation system: instead of strictly written lines in the code, all interface texts (buttons, notifications, menus) are stored in separate files - language packages. These packages are downloaded from Telegram servers upon request and can be updated regardless of the application version.

Each package is a JSON file with pairs "key": "value", where the key is the internal string identifier (for example, "ActionCancel"), and the value is its translation. Example structure:

{
"ActionCancel": "Cancel",
"DialogFilterAll": "All chats",
"ErrorUnknown": "Unknown error"
}

When you select a language in the Telegram settings (Settings → Language), the application downloads the corresponding package from the server. Custom languages are downloaded via the Bot API, but are not moderated - only you and those to whom you send a link to installation.

Advantages of this approach:

• 🔄 Independence from updates: you can update the translation without waiting for the release of a new version of Telegram.
• 🌍 Support for dialects: for example, separate packages for the Ukrainian and Crimean Tatar versions.
• 🛠️ Flexibility: you can translate only part of the interface (for example, only privacy settings).

⚠️ Attention: Telegram limits the number of custom languages loaded at the same time - if you test several packages, old ones may be automatically deleted. To save the translation, export it to a file.

Preparation: tools and requirements

To create a language pack you will need:

• 📱 Android device with Telegram installed (version no lower 9.0).
• 💻 Computer (Windows, macOS or Linux) for editing JSON files.
• 📝 Text editor with JSON support: VS Code, Notepad++ or Sublime Text.
• 🤖 Bot API: bot token for downloading the package (you can get it through @BotFather).
• 🌐 Internet access for validation and downloading the package.

We also recommend:

• 🔍 JSON validator (for example, JSONLint) for verification syntax.
• 📁 Git (optional), if you plan to collaborate with other translators.

If you have never worked with JSON, don’t worry: the format is intuitive - don't forget commas between key-value pairs and keep track. quotes (they should be double " ", not single).

Step 1: Get a language pack template

Telegram does not provide a blank template for translations - instead you need export the current language and use it as a basis:

1. Open it. Telegram on Android.
2. Go to Settings → Language.
3. Select any language (for example, English).
4. Click on the three dots (⋮) in the upper right corner and select "Export language".
5. The file telegram_translation.json will be saved in the folder Download of your device.

Now transfer this file to your computer. Do not change its name — Telegram expects exactly this format when import.

If you want to create a language from scratch, you can download the current template from the Telegram repository on GitHub:

• 🔗 Go to official repository.
• Download the file languages/english.json (or other base language).

⚠️ Attention: Templates from the repository may contain lines that have not yet been added to the mobile version of Telegram. Before downloading, remove unnecessary keys, otherwise the package will not pass validation.

Download the current language from Telegram|Transfer the file to your computer|Check JSON for errors|Remove unnecessary keys-->

Step 2: Editing the translation

Open the downloaded JSON file in a text editor. You will see a structure like:

{
"ln": "ru",
"ln_name": "Russian",
"strings": {
"ActionCancel": "Cancel",
"DialogFilterAll": "All chats",
...
}
}

Main fields that you need change:

Field	Description	Example value
ln	Language code (2 characters, ISO 639-1 standard)	"pir" (pirate English)
ln_name	Language name (displayed in Telegram settings)	"Pirate"
strings	Translation dictionary (key = original string, value = translation)	"ActionCancel": "Cancel!"
plural_rules	Plural rules (optional, for languages with complex forms)	"nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);"

Examples of string replacement:

• 🔄 Replace "ActionCancel": "Cancel" with "ActionCancel": "Stop!".
• 🔄 Change "DialogFilterAll": "All chats" to "DialogFilterAll": "All bottles" (for pirate theme).

Important rules:

• 🚫 Do not remove the keys (the left part before the colon) - just change the values.
• 🚫 Do not use special characters (\n, \t) without escaping.
• 🚫 The maximum line length is 255 characters.

Step 3: Validation and verification of JSON

Before uploading the package to Telegram, you need to check it for errors. Even one missing comma or extra parenthesis will make the file invalid.

Validation methods:

1. Online validators:
   • 🔗 JSONLint —insert the code and click Validate.
   • 🔗 JSON Formatter —visualizes the structure.
2. Local check:
   • In VS Code install the extension JSON Tools —it highlights errors in real time.
   • In Notepad++ use the plugin JSON Viewer.

Typical errors and how to fix them:

Error	Cause	Solution
Unexpected token	Extra comma or parenthesis	Remove the last comma in object or array
Invalid string	Unescaped quotes inside a value	Replace " with \"
Duplicate key	Duplicate key (for example, two strings "ActionCancel")	Remove duplicate

After correcting errors, save the file in encoding UTF-8 without BOM (this is important for the correct display of Cyrillic and emoji).

What happens if you load invalid JSON?

Telegram will return an error "INVALID_JSON", and a message will appear in the bot logs "Failed to parse language pack". In this case, the package itself will not be saved, and you will have to correct the file and download it again.

Step 4: Uploading the package via Bot API

To upload a custom language to Telegram, you need a bot with rights to work with language packs. Here are step-by-step guide:

1. Create a bot:
   • Open a chat with @BotFather.
   • Send a command /newbot.
   • Come up with a name and username (for example, MyLangBot).
   • Copy the bot token (example: 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).
2. Send a JSON file to the bot:
   • Open a chat with your bot in Telegram.
   • Attach the edited file telegram_translation.json.
3. Activate the package:
   • Follow the link like:

     https://t.me/setlanguage?lang_code=YOUR_BOT_TOKEN

     (replace YOUR_BOT_TOKEN with the bot token).

   • Telegram will offer to apply a new language - confirm.

If after downloading the language does not appear in the settings, check: 1) the correctness of the bot token, 2) the absence of errors in JSON, 3) compliance of the language code (ln) with the ISO 639-1 standard.

⚠️ Attention: Telegram caches language packs. If you updated the translation, but the changes are not displayed, try restarting the application or clearing the cache in the Android settings (Settings → Applications → Telegram → Storage → Clear cache).

Step 5: Testing and debugging

After loading the language, check its operation:

• 🔍 Interface: open the main sections of Telegram (Chats, Contact, Settings) and make sure that all lines are displayed correctly.
• 🔍 Notifications: ask a friend to send you a message and check the text push notifications.
• 🔍 Keyboard: some lines (for example, "StickerSend") refer to the built-in Telegram keyboard.

Typical problems and solutions:

Problem	Possible cause	Solution
Some lines in English	Missing translation for the key	Add missing lines in JSON
Characters are displayed as scratchy	Incorrect file encoding	Save the file in UTF-8 without BOM
The language disappeared after restarting Telegram	Validation error on the server	Check the bot logs for errors

To debug complex cases, use bot log:

1. Open chat with @BotFather.
2. Select your bot and click Set commands → Edit Bot Settings → Enable Logging.
3. Logs will be sent to the chat specified during setup.

Additional features: plugins and automation

If you plan to maintain the language long-term or collaborate with other translators, consider these tools:

• 🤖 Collaboration bots:
  • @TranslationBot —allows multiple users edit one package.
  • @LangPackBot —automatically checks JSON for errors.
• 🛠️ Scripts for automation:
  • Use Python with the library python-telegram-bot for mass string replacement.
  • Example script for replacing all "OK" with "Gut":

    import json
    with open('telegram_translation.json', 'r', encoding='utf-8') as f:
    data = json.load(f)
    for key in data['strings']:
    if data['strings'][key] == 'OK':
    data['strings'][key] = 'Gut'
    with open('telegram_translation_updated.json', 'w', encoding='utf-8') as f:
    json.dump(data, f, ensure_ascii=False, indent=2)

For languages with complex grammatical rules (for example, Arabic or Japanese) it can need to configure plural_rules and rtl (for languages written from right to left). Example for Arabic:

{
"ln": "ar",
"ln_name": "العربية",
"rtl": true,
"plural_rules": "nplurals=6; plural=n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n%100>=3 && n%100<=10 ? 3 : n%100>=11 ? 4 : 5;"
}

⚠️ Attention: Plural rules must strictly comply with the standard gettext. An error in the formula will lead to incorrect display of numbers (for example, “1 message” instead of “1 message”).

FAQ: Frequently asked questions about custom languages in Telegram

Is it possible to create a language without a bot?

No, downloading custom language packs in Telegram is only possible through Bot API. An alternative way is to manually edit the application files (requires root access and may break Telegram after an update).

How many languages ​​can be downloaded through one bot?

There are no limits on the number of packages, but Telegram can block a bot if it downloads too many languages ​​in a short period of time (risk of spam). We recommend creating a separate bot for each language.

How to share your language with friends?

Send them a link like https://t.me/setlanguage?lang_code=YOUR_BOT_TOKEN. They will be able to install the language through this link, but package updates will only come if the bot is active.

Why are some strings not translated?

This may be due to:

• Missing a key in your JSON (check the current template).
• An error in the name key (case matters: "actioncancel" ≠ "ActionCancel").
• Caching (try reinstalling Telegram).

Is it possible to return the standard language after installing a custom one?

Yes, go to Settings → Language and select any official language (for example, English or Russian). Custom languages are displayed in a separate section "Other".