diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e389331bce4..331ef37b8ce 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,4 +5,4 @@
### Thank you for your interest in contributing!
-Please see [our contributing guide on documentation](/v3/contribute/) for the latest information on how to contribute!
+Please see [our contributing guide on documentation](https://docs.ton.org/v3/contribute) for the latest information on how to contribute!
diff --git a/README.md b/README.md
index 44b3f80943a..edb9677602a 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,10 @@
-## TON Blockchain Documentation 📚
+## TON documentation 📚
This is the official repository for The Open Network documentation.
Latest documentation release: [docs.ton.org](https://docs.ton.org)
-
-The mission of this documentation is to collect all available information and knowledge that can help TON developers.
-
-You can improve the documentation by following steps below.
---
@@ -30,29 +26,28 @@ Join TON Docs Club chat in Telegram to join contributors party:
## How to Contribute? 🦄
-If you are a developer and faced some difficulties, successfully overcoming them - share this knowledge with future developers!
-
— Have an issue? [Prepare a solution with TON Docs Wizard](https://t.me/ton_docs_bot).
— Have an idea? [Submit a Feature Request](https://github.com/ton-community/ton-docs/issues/new/choose).
-— Want to contribute? [Setup your environment](https://github.com/ton-community/ton-docs#set-up-your-environment-%EF%B8%8F).
+— Want to contribute? [How to contribute](https://docs.ton.org/v3/contribute).
+— Want to translate? [Localization](https://docs.ton.org/v3/contribute/localization-program/how-to-contribute)
+
-Contributing best practices: [docs/contribute](/v3/contribute)
---
-## Set up your Environment ☁️
+## Set up your environment ☁️
-If you are changing the sidebar or adding media-files, please check that your submission will not break production.
+If you're changing the sidebar or adding media-files, links, please make sure that your submission won't break production.
You can do this in two ways:
-### Cloud (quick way)
+### Cloud
-Use Gitpod (a free, online VS code-like IDE) for contributing. It will launch a workspace with a single click:
+Use Gitpod for contributing. It'll launch a workspace with a single click:
[](https://gitpod.io/#https://github.com/ton-community/ton-docs)
-### Local (default way)
+### Local
1. Download repository from GitHub with its submodules
@@ -81,14 +76,14 @@ Use Gitpod (a free, online VS code-like IDE) for contributing. It will launch a
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
-## Install Recursive Module
+## Install recursive module
-If you cloned the repository from GitHub without step 1, you will need to install the submodules to enable local execution.
+If you cloned the repository from GitHub without step 1, you'll need to install the submodules to enable local execution.
```
git submodule update --init --recursive
```
-## Contributors Wall
+## Contributors wall
diff --git a/docs/v3/contribute/localization-program/how-it-works.md b/docs/v3/contribute/localization-program/how-it-works.md
index 31ccf07486c..bc76661ddb1 100644
--- a/docs/v3/contribute/localization-program/how-it-works.md
+++ b/docs/v3/contribute/localization-program/how-it-works.md
@@ -2,46 +2,46 @@
-The **TownSquare Labs Localization Program** comprises several key components. This chapter will provide an overview of how the program operates, helping you understand its workings and how to use it effectively.
+The TownSquare Labs Localization Program comprises several key components. This chapter provides an overview of localization, helping you understand how it works and how to use it effectively.
Within this system, we integrate several applications to function seamlessly as a unified program:
- **GitHub**: Hosts the documentation, synchronizes docs from the upstream repository, and syncs translations to specific branches.
- **Crowdin**: Manages translation processes, including translating, proofreading, and setting language preferences.
- **AI Systems**: Utilizes advanced AI to assist translators, ensuring smooth workflow.
-- **Customized Glossary**: Guides translators and ensures AI generates accurate translations based on the project’s context. Users can also upload their glossaries as needed.
+- **Customized Glossary**: This glossary guides translators and ensures AI generates accurate translations based on the project’s context. Users can also upload their glossaries as needed.
:::info
-This guide won't cover the entire process in detail, but it will highlight the key components that make the TownSquare Labs Localization Program unique. You can explore the program further on your own.
+This guide won't cover the entire process but will highlight the key components that make the TownSquare Labs Localization Program unique. You can explore the program further on your own.
:::
-## GitHub Synchronization for Documentation and Translations
+## GitHub synchronization for documentation and translations
-Our repository utilizes several branches for managing documentation and translations. Below is a detailed explanation of the purpose and function of each special branch:
+Our repository utilizes several branches to manage documentation and translations. Below is a detailed explanation of the purpose and function of each special branch:
-### Branches Overview
+### Branches overview
- **`dev`**
The `dev` branch runs GitHub Actions to handle synchronization tasks. You can find the workflow configurations in the [**`.github/workflows`**](https://github.com/TownSquareXYZ/ton-docs/tree/dev/.github/workflows) directory:
- **`sync-fork.yml`**: This workflow synchronizes documentation from the upstream repository. It runs daily at 00:00.
- - **`sync-translations.yml`**: This workflow synchronizes updated translations to the respective language branches for preview purposes on the corresponding language websites.
+ - **`sync-translations.yml`**: This workflow synchronizes updated translations to the respective language branches for preview purposes on the corresponding websites.
- **`main`**
- This branch stays in sync with the upstream repository through GitHub Actions running on the `dev` branch. It is also used for updating certain codes that we intend to propose to the original repository.
+ This branch stays in sync with the upstream repository through GitHub Actions, which runs on the `dev` branch. It also updates specific codes we intend to propose to the original repository.
- **`l10n_main`**
- This branch includes all changes from the `main` branch and translations from Crowdin. All modifications in this branch are periodically committed to the upstream repository by using a new sub-branch named `l10n_main_[some data]`.
+ This branch includes all changes from the `main` branch and translations from Crowdin. All modifications in this branch are periodically committed to the upstream repository using a new sub-branch named `l10n_main_[some data]`.
- **`l10n_feat` or `l10n_feat_[specific functions]`**
- This branch will include changes to code or documentation related to the translation system. Once all content is finalized, the changes in this branch will be merged into `l10_main`.
+ This branch will include changes to code or documentation related to the translation system. Once you finalize all content, the changes in this branch will be merged into `l10_main`.
- **`[lang]_preview`**
These branches are designated for specific language previews, such as `ko_preview` for Korean and `ja_preview` for Japanese. They allow us to preview the website in different languages.
By maintaining these branches and using GitHub Actions, we efficiently manage the synchronization of our documentation and translation updates, ensuring that our multilingual content is always up to date.
-## How to Set Up a New Crowdin Project
+## How to set up a new crowdin project
1. Log in to your [**Crowdin account**](https://accounts.crowdin.com/login).
2. Click `Create new project` in the menu.
@@ -69,41 +69,41 @@ By maintaining these branches and using GitHub Actions, we efficiently manage th
- **preserve_hierarchy**: Maintains the GitHub directory structure on the Crowdin server.
- **source** and **translation**: Specify the paths for the files to upload to Crowdin and where the translated files should be output.
- Refer to [**our official config file**](https://github.com/TownSquareXYZ/ton-docs/blob/localization/crowdin.yml) for an example.
- More details can be found in the [**Crowdin configuration documentation**](https://developer.crowdin.com/configuration-file/).
+ For an example, refer to the [**config file**](https://github.com/TownSquareXYZ/ton-docs/blob/localization/crowdin.yml).
+ Find more in the [**Crowdin configuration documentation**](https://developer.crowdin.com/configuration-file/).
6. Configure Crowdin to connect to your GitHub repo:
1. Click `Add Repository` and select `Source and translation files mode`.
2. Connect your GitHub account and search for the repo you want to translate.
- 3. Select the branch on the left, which will generate a new branch where Crowdin will post the translations.
+ 3. Select the branch on the left to generate a new branch where Crowdin will post the translations.
- 4. Choose the frequency for updating translations to your GitHub branch. Default settings can be kept for other configurations, then click save to enable the integration.
+ 4. Choose the frequency for updating translations to your GitHub branch, then click save to enable the integration.
-Refer to the [**GitHub integration documentation**](https://support.crowdin.com/github-integration/) for more details.
+Find more details in the [**GitHub integration documentation**](https://support.crowdin.com/github-integration/).
7. Finally, you can click the `Sync Now` button to sync the repo and translations whenever needed.
## Glossary
-### What is a Glossary?
+### What is a glossary?
-Sometimes, AI translators can't recognize specific terms that shouldn't be translated. For instance, we don't want "Rust" translated when referring to the programming language. To prevent such mistakes, we use a glossary to guide translations.
+Sometimes, AI translators can't recognize untranslatable and specific terms. For instance, we don't want "Rust" translated when referring to the programming language. To prevent such mistakes, we use a glossary to guide translations.
-A **glossary** allows you to create, store, and manage project-specific terminology in one place, ensuring terms are translated correctly and consistently.
+A **glossary** allows you to create, store, and manage project-specific terminology in one place, ensuring that terms are translated correctly and consistently.
-You can check our [**ton-i18n-glossary**](https://github.com/TownSquareXYZ/ton-i18n-glossary) for reference.
+You can reference our [**ton-i18n-glossary**](https://github.com/TownSquareXYZ/ton-i18n-glossary).
-### How to Set Up a Glossary for a New Language?
+### How to set up a glossary for a new language?
Most translation platforms support glossaries. In Crowdin, after setting up a glossary, each term appears as an underlined word in the Editor. Hover over the term to see its translation, part of speech, and definition (if provided).
-In DeepL, simply upload your glossary, and it will be used automatically during AI translation.
+In DeepL, upload your glossary, which will be used automatically during AI translation.
We have created [**a program for glossary**](https://github.com/TownSquareXYZ/ton-i18n-glossary) that auto-uploads updates.
@@ -111,22 +111,24 @@ To add a term to the glossary:
1. If the English term already exists in the glossary, find the corresponding line and column for the language you want to translate, input the translation, and upload it.
2. To upload a new glossary, clone the project and run:
- - `npm i`
- - `npm run generate -- `
+```bash
+npm i
+```
+```bash
+npm run generate --
+```
Repeat step 1 to add the new term.
-**Simple and efficient, isn’t it?**
-
-## How to Take Advantage of AI Translation Copilot?
+## How to take advantage of AI translation copilot?
AI translation copilot helps break down language barriers with several advantages:
- **Enhanced Consistency**: AI translations are based on up-to-date information, providing the most accurate and current translations.
- **Speed and Efficiency**: AI translation is instantaneous, handling large volumes of content in real-time.
-- **Robust Scalability**: AI systems continuously learn and improve, enhancing translation quality over time. With the provided glossary, AI translations can be tailored to the specific needs of different repositories.
+- **Robust Scalability**: AI systems continuously learn and improve, enhancing translation quality over time.
-To use AI translation in Crowdin (we use DeepL in our project):
+We use DeepL for AI translation in our Crowdin project:
1. Select Machine Translation in the Crowdin menu and click edit on the DeepL line.
2. Enable DeepL support and input the DeepL Translator API key.
@@ -138,7 +140,7 @@ To use AI translation in Crowdin (we use DeepL in our project):
4. In the repo, click Pre-translation and select via Machine Translation.
-5. Choose DeepL as the Translation Engine, select the target languages, and select the files to translate.
+5. Choose DeepL as the Translation Engine, select the target languages, and select the translated files.
-That's it! Now you can take a break and wait for the pre-translation to complete.
\ No newline at end of file
+That's it! Now, you can take a break and wait for the pre-translation to complete.
diff --git a/docs/v3/contribute/localization-program/how-to-contribute.md b/docs/v3/contribute/localization-program/how-to-contribute.md
index caa9ca7885b..dbc51eb0d9f 100644
--- a/docs/v3/contribute/localization-program/how-to-contribute.md
+++ b/docs/v3/contribute/localization-program/how-to-contribute.md
@@ -1,58 +1,57 @@
# How to contribute
-:::info
-This page explains how to participate in localization program for TON documentation.
-:::
+This page explains how to participate in the localization program for TON documentation.
## Prerequisites
-The **TownSquare Labs Localization Program** is open to everyone! Here are a few steps you need to take before you start contributing:
+Localization contribution is open to everyone. Here are a few steps you need to take before you start contributing:
-1. Log in to your [**Crowdin**](https://crowdin.com) account or sign up.
+1. Log in to your [Crowdin](https://crowdin.com) account or sign up.
2. Select the language you want to contribute to.
-3. Familiarize yourself with the [**How to Use Crowdin**](/v3/contribute/localization-program/how-to-contribute) guide and the [**Translation Style Guide**](/v3/contribute/localization-program/translation-style-guide) for tips and best practices.
-4. Use machine translations to aid your work but do not rely solely on them.
-5. All translation results can be previewed on the website one hour after they have been proofread.
+3. Familiarize yourself with the [How to use crowdin](/v3/contribute/localization-program/how-to-contribute/) guide and the [Translation style guide](/v3/contribute/localization-program/translation-style-guide/) for tips and best practices.
+4. Use machine translations to aid your work, but do not rely solely on them.
+5. Preview all translation results on the website after proofreading.
+
+:::info
+Before contributing, read the guidelines below to ensure standardization and quality, speeding up the review process.
+:::
+
+## Side-by-side mode
+
+All tasks are performed in **side-by-side** mode in the Crowdin Editor. To enable this, click a file you want to work on. At the top right of the page, click the **Editor view** button and select **side-by-side** mode for a clearer editor view.
+
## Roles
Here are the **roles** you can assume in the system:
- **Language Coordinator** – Manages project features within assigned languages.
-- **Developer** – Uploads files, edits translatable text, connects integrations, and uses the API.
+- **Developer** – Uploads files, edits translatable text, connects integrations and uses the API.
- **Proofreader** – Translates and approves strings.
- **Translator** (in-house or community) – Translates strings and votes on translations added by others.
-Our localization project is hosted on [Crowdin](https://crowdin.com/project/ton-docs).
-
-:::info
-Before you start contributing, **read the guidelines below** to ensure standardization and quality, making the review process much faster.
-
-## Side-by-Side Mode
+The localization project is hosted on [Crowdin](https://crowdin.com/project/ton-docs).
-All tasks are performed in **side-by-side** mode in the Crowdin Editor. To enable this, click a file you want to work on. At the top right of the page, click the **Editor view** button and select **side-by-side** mode for a clearer editor view.
-
-:::
-### Language Coordinator
-- **Translate and approve strings**
-- **Pre-translate project content**
-- **Manage project members and join requests**
+### Language coordinator guidelines
+- Translate and approve strings
+- Pre-translate project content
+- Manage project members and join requests
-- **Generate project reports**
+- Generate project reports
-- **Create tasks**
+- Create tasks
-### Developer
-- **Update Footer Configuration for Your Language :**
- 1. Fork our [**repository**](https://github.com/TownSquareXYZ/ton-docs/tree/i18n_feat).
+### Developer guidelines
+- **Update footer configuration for your language:**
+ 1. Fork our [repository](https://github.com/TownSquareXYZ/ton-docs/tree/i18n_feat).
2. Locate the file [**`src/theme/Footer/config.ts`**](https://github.com/TownSquareXYZ/ton-docs/blob/main/src/theme/Footer/config.ts).
3. Copy the value of the variable **`FOOTER_COLUMN_LINKS_EN`** to **`FOOTER_COLUMN_LINKS_[YOUR_LANG]`**.
4. Translate the values of the keys **`headerLangKey`** and **`langKey`** to your language, as we did for Mandarin in **`FOOTER_COLUMN_LINKS_CN`**.
5. Add a new property to **`FOOTER_LINKS_TRANSLATIONS`**:
- Set **the key** as your [**ISO language code**](https://www.andiamo.co.uk/resources/iso-language-codes/) (**two letters**, **lowercase**).
- - **The value** should be the new variable you just created for your language.
+ - **The value** should be the new variable you created for your language.
6. Run the command **`yarn start:local [YOUR_IOS_LANG_CODE]`** to preview the new footer in your language.
(e.g., **`yarn start:local ru`** for a preview of the **Russian** footer)
7. If everything looks good, create a pull request to the **`i18n_feat`** branch.
@@ -62,13 +61,13 @@ All tasks are performed in **side-by-side** mode in the Crowdin Editor. To enabl
- **Use the [Crowdin API](https://developer.crowdin.com/api/v2/)**
-### Proofreader
+### Proofreader guidelines
As a **Proofreader**, you'll work on files with a **blue progress bar**.
Click on a file to enter the editing interface.
-#### Let's Start Contributing
+#### Contribution flow
1. Make sure you're in [**side-by-side mode**](#side-by-side-mode). Filter by **Not Approved** translations to see strings needing proofreading.
@@ -81,23 +80,23 @@ Click on a file to enter the editing interface.
:::info
-You can also review approved lines:
+You can also review the approved lines:
1. Filter by **Approved**.
2. If an approved line has issues, click the ☑️ button to revert it to needing proofreading.
:::
-3. To move to the next file, click the file name at the top, select the new file from the pop-up window, and continue proofreading.
+3. To move to the following file, click the file name at the top, select the new file from the pop-up window, and continue proofreading.
-#### Previewing Your Work
-Every approved content will be deployed to a preview website within one hour. Check [**our repo**](https://github.com/TownSquareXYZ/ton-docs/pulls) for the **preview** link in the newest PR.
+#### Previewing your work
+The preview website displays all approved content within one hour. Check [**our repo**](https://github.com/TownSquareXYZ/ton-docs/pulls) for the **preview** link in the newest PR.
-### Translator
+### Translator guidelines
-As a **Translator**, your goal is to ensure translations are faithful and expressive, making them as close to the original meaning and as understandable as possible. Your mission is to make the **blue progress bar** reach 100%.
+As a translator, you aim to ensure that translations are faithful and expressive, keeping them as close to the original meaning and as understandable as possible. Your mission is to make the blue progress bar reach 100%.
-#### Let's Start Translating
+#### Translation flow
Follow these steps for a successful translation process:
@@ -118,15 +117,15 @@ Follow these steps for a successful translation process:
5. To move to the next file, click the file name at the top and select the new file from the pop-up window.
-## How to Add Support for a New Language
+## How to add support for a new language
-Currently, we have all desired languages in Crowdin. If you are a community manager, follow these steps:
+If you are a community manager, follow these steps:
1. Add a new branch named `[lang]_localization` (e.g., `ko_localization` for Korean) on [TownSquareXYZ/ton-docs](https://github.com/TownSquareXYZ/ton-docs).
2. **Contact the Vercel owner of this repo** to add the new language to the menu.
3. Create a PR request to the dev branch. **Do not merge to dev**; this is for preview purposes only.
-Once these steps are completed, you can see the preview of your language in the PR request.
+Once you complete these steps, you can see the preview of your language in the PR request.
When your language is ready for the TON docs, create an issue, and we'll set your language into the production environment.
diff --git a/docs/v3/contribute/localization-program/overview.md b/docs/v3/contribute/localization-program/overview.md
index 78e794e3750..9b58329a4cd 100644
--- a/docs/v3/contribute/localization-program/overview.md
+++ b/docs/v3/contribute/localization-program/overview.md
@@ -1,22 +1,22 @@
-# Localization program
+# Localization
-The Translation Program is a collaborative effort to translate various documents related to TON into multiple languages, making the website more accessible to billions of non-English speakers worldwide.
+The localization is a collaborative effort to translate various TON-related documents into multiple languages, making the website accessible to billions of non-English speakers worldwide.
-## System Design Philosophy
+## System design philosophy
-The localization program is **launched** and **actively maintained** by [**TownSquare Labs**](https://github.com/TownSquareXYZ), one of the closest partners of **TON**.
+The localization process is fully maintained by [TownSquare Labs](https://github.com/TownSquareXYZ).
-We are committed to creating an open infrastructure for multilingual community collaboration to **advance TON to a better phase**, which includes:
+TownSquare is committed to creating an open infrastructure for multilingual community collaboration to advance TON to a better phase, which includes:
* **Suitable for multilingual communities**
The program supports multiple languages, ensuring inclusivity and ease of access for users from diverse linguistic backgrounds.
* **Automate development, integration, and deployment**
- Through automation tools, the program simplifies development, integration, and deployment, reducing manual efforts and enhancing efficiency and consistency across localization efforts.
+ The program simplifies development, integration, and deployment through automation tools, reducing manual efforts and enhancing efficiency and consistency across localization efforts.
* **Separation of roles for developer, translator, and verifier**
- Our approach divides the responsibilities of developers, translators, and verifiers, allowing each role to focus on their tasks, ensuring high-quality translations and seamless collaboration without role conflicts.
+ Our approach divides the responsibilities of developers, translators, and verifiers, allowing each role to focus on their tasks and ensuring high-quality translations and seamless collaboration without role conflicts.
* **Incentives for community contributions**
We offer incentives for community members who contribute to localization efforts. This fosters active participation, rewards contributors, and promotes a sense of ownership and community engagement.
@@ -24,13 +24,13 @@ We are committed to creating an open infrastructure for multilingual community c
* **Advanced AI system integration**
AI systems improve translation accuracy and efficiency by offering intelligent suggestions and automating repetitive tasks, ensuring high-quality outcomes with reduced effort.
-This project is designed to support speakers of multiple languages, with the goal of serving the global developer ecosystem.
+This project is designed to support speakers of multiple languages and serve the global developer ecosystem.
## Acknowledgments
-We sincerely appreciate the thousands of community members who are integral to the Translation Program. We aim to acknowledge our translators and support their career growth. In the future, we plan to create leaderboards and a list of all contributors to the program.
+We sincerely appreciate the thousands of community members integral to the Translation Program. We aim to acknowledge our translators and support their career growth. In the future, we plan to create leaderboards and a list of all contributors.
-## Guides and Resources
+## Guides and resources
If you are participating in or considering joining the Translation Program, refer to the translation guides below:
-* [**Translation Style Guide**](/v3/contribute/localization-program/translation-style-guide) – Instructions and tips for translators.
-* [**Crowdin Online Editor Guide**](https://support.crowdin.com/online-editor/) – An in-depth guide to using the Crowdin online editor and some of Crowdin's advanced features.
+* [Translation style guide](/v3/contribute/localization-program/translation-style-guide) – Instructions and tips for translators.
+* [Crowdin online editor guide](https://support.crowdin.com/online-editor/) – An in-depth guide to using the Crowdin online editor and some of Crowdin's advanced features.
diff --git a/docs/v3/contribute/localization-program/translation-style-guide.md b/docs/v3/contribute/localization-program/translation-style-guide.md
index 1285dbd9490..c126cf59b62 100644
--- a/docs/v3/contribute/localization-program/translation-style-guide.md
+++ b/docs/v3/contribute/localization-program/translation-style-guide.md
@@ -1,45 +1,43 @@
# Translation style guide
-This translation style guide contains some of the most important guidelines, instructions, and tips for translators, helping us localize the website.
+This translation style guide contains essential guidelines, instructions, and tips for translators, helping us localize the website.
-This document serves as a general guide and is not specific to any one language.
+This document serves as a general guide and is not specific to any language.
## Capturing the essence of the message
When translating TON docs content, avoid literal translations.
-It is important that the translations capture the essence of the message. This could mean rephrasing certain phrases, or using descriptive translations instead of translating the content word for word.
+The translations must capture the essence of the message. This approach means rephrasing specific phrases or using descriptive translations instead of translating the content word for word.
-Different languages have different grammar rules, conventions and word order. When translating, please be mindful of how sentences are structured in the target languages, and avoid literally translating the English source, as this can lead to poor sentence structure and readability.
+Different languages have different grammar rules, conventions, and word order. When translating, please be mindful of structuring sentences in the target languages, and avoid word-for-word translation of the English source, as this can lead to poor sentence structure and readability.
-Instead of translating the source text word for word, it is recommended you read the entire sentence and adapt it to fit the conventions of the target language.
+Instead of translating the source text word for word, you should read the entire sentence and adapt it to fit the conventions of the target language.
## Formal vs. informal
We use the formal form of address, which is always polite and appropriate for all visitors.
-Using the formal address allows us to avoid sounding unofficial or offensive, and works regardless of the visitor’s age and gender.
+Using the formal address allows us to avoid sounding unofficial or offensive and works regardless of the reader’s age and gender.
-Most Indo-European and Afro-Asiatic languages use gender-specific second-person personal pronouns, which distinguish between male and female. When addressing the user or using possessive pronouns, we can avoid assuming the visitor’s gender, as the formal form of address is generally applicable and consistent, regardless of how they identify.
+Most Indo-European and Afro-Asiatic languages use gender-specific second-person personal pronouns, distinguishing between males and females. When addressing the user or using possessive pronouns, we can avoid assuming the reader’s gender, as the formal address is generally applicable and consistent, regardless of how they identify.
-## Simple and clear vocabulary and meaning
+## Straightforward vocabulary and meaning
Our goal is to make content on the website understandable to as many people as possible.
-In most cases, this can be easily achieved by using short and simple words that are easily understandable. If there are multiple possible translations for a certain word in your language with the same meaning, the best option is most often the shortest word that clearly reflects the meaning.
+In most cases, contributors can achieve this result by using short and simple words that are easily understandable. If multiple possible translations exist for a word in your language with the same meaning, the best option is often the shortest word reflecting the meaning.
## Writing system
-All of the content should be translated using the correct writing system for your language, and should not include any words, written using Latin characters.
+All of the content should be translated using the correct writing system for your language and should not include any words written using Latin characters.
When translating the content, you should ensure that the translations are consistent and do not include any Latin characters.
-**The above doesn’t apply to languages, where proper names shouldn’t be translated as a rule.**
+**Do not translate proper names defined by glossary**
## Translating page metadata
-Some pages contain metadata on the page, like 'title', 'lang', 'description', 'sidebar', etc.
+Some pages contain metadata, such as 'title', 'lang', 'description', 'sidebar', etc.
-We hide the content that translators should never translate when uploading new pages to Crowdin, meaning that all the metadata visible to translators in Crowdin should get translated.
+When uploading new pages to Crowdin, we hide content that translators should never translate. This feature makes visible to translators in Crowdin only the text that should be translated.
-Please be especially mindful when translating any strings where the source text is 'en'. This represents the language that the page is available in and should be translated to the [ISO language code for your language](https://www.andiamo.co.uk/resources/iso-language-codes/). These strings should always be translated using Latin characters, not the writing script, native to the target language.
-
-If you are unsure which language code to use, you can check the translation memory in Crowdin or find the language code for your language in the URL of the page in the Crowdin online editor.
+Please be especially careful when translating strings where the source text is 'en'. This represents the language page, which is available and should be translated to the [ISO language code for your language](https://www.andiamo.co.uk/resources/iso-language-codes/). These strings should always be translated using Latin characters, not the writing script, native to the target language.
Some examples of language codes for the most widely spoken languages:
@@ -51,55 +49,55 @@ Some examples of language codes for the most widely spoken languages:
* Ukrainian - uk
## Titles of external articles
-Some strings contain titles of external articles. Most of our developer documentation pages contain links to external articles for further reading. The strings containing titles of articles need to be translated, regardless of the article's language, to ensure a more consistent user experience for the visitors viewing the page in their language.
+Some strings contain titles of external articles. Most of our developer documentation pages contain links to external articles for further reading. The strings containing article titles need to be translated, regardless of the article's language, to ensure a more consistent user experience for visitors viewing the page in their language.
## Crowdin warnings
-Crowdin has a built-in feature that warns translators when they are about to make a mistake. Crowdin will automatically warn you of this before saving your translation if you forget to include a tag from the source, translate elements that should not be translated, add several consecutive spaces, forget end punctuation, etc. If you see a warning like this, please go back and double-check the suggested translation.
+Crowdin has a built-in feature that warns translators when they are about to make a mistake. Crowdin will automatically alert you before saving your translation if you forget to include a tag from the source, translate elements that should not be translated, add several consecutive spaces, forget end punctuation, etc. If you see a warning like this, please double-check the suggested translation.
:::warning
-Never ignore these warnings, as they usually mean that something is wrong, or that the translation is missing a key part of the source text.
+Never ignore these warnings, as they usually mean something is wrong or the translation lacks a key part of the source text.
:::
-## Short vs. full forms/abbreviations
-There are a lot of abbreviations used on the website, e.g. dapps, NFT, DAO, DeFi, etc. These abbreviations are commonly used in English and most visitors to the website are familiar with them.
+## Short vs. complete forms and abbreviations
+The website uses many abbreviations, such as apps, DApps, NFT, DAO, DeFi, etc. These abbreviations are standard in English, and most visitors are familiar with them.
-Since they usually don’t have established translations in other languages, the best way to approach these and similar terms is to provide a descriptive translation of the full form, and add the English abbreviation in brackets.
+Since they usually don’t have established translations in other languages, the best approach to these and similar terms is to provide a descriptive translation of the entire form and add the English abbreviation in brackets.
-Do not translate these abbreviations, since most people wouldn’t be familiar with them, and the localized versions would not make much sense to most visitors.
+Do not translate these abbreviations since most people are unfamiliar with them, and the localized versions would not make much sense to most visitors.
-Example of how to translate dapps:
+Example of how to translate DApps:
-* Decentralized applications (dapps) → Translated full form (English abbreviation in brackets)
+* Decentralized applications (DApps) → Translated in complete form (English abbreviation in brackets)
## Terms without established translations
-Some terms might not have established translations in other languages, and are widely known by the original English term. Such terms mostly include newer concepts, like proof-of-work, proof-of-stake, Beacon Chain, staking, etc.
+Some terms might not have established translations in other languages but are widely known by their original English names. Such terms include newer concepts, like proof-of-work, proof-of-stake, Beacon Chain, staking, etc.
-While translating these terms can sound unnatural, since the English version is commonly used in other languages as well, it is highly recommended that they are translated.
+While translating these terms can sound unnatural, since the English version is a basis for other languages, it is highly recommended that they be translated.
-When translating them, feel free to get creative, use descriptive translations, or simply translate them literally.
+Feel free to get creative, use descriptive translations, or translate them literally.
-The reason why most terms should be translated, instead of leaving some in English, is the fact that this new terminology will become more widespread in the future, as more people start using TON and related technologies. If we want to onboard more people from all over the world to this space, we need to provide understandable terminology in as many languages as possible, even if we need to create it ourselves.
+Most terms should be translated instead of leaving some in English, as this new terminology will become more widespread as more people start using TON and related technologies. To onboard more people to TON, we must provide understandable terminology in as many languages as possible, even if we need to create it ourselves.
## Buttons & CTAs
-The website contains numerous buttons, which should be translated differently than other content.
+Do not translate the website's contents, such as buttons.
-Button text can be identified by viewing the context screenshots, connected with most strings, or by checking the context in the editor, which includes the phrase ‘’button’’.
+You may identify button text by viewing the context screenshots connected with most strings or by checking the context in the editor, which includes the phrase ‘’button’’.
-The translations for buttons should be as short as possible, to prevent formatting mismatches. Additionally, button translations should be imperative, i.e. present a command or request.
+Button translations should be as short as possible to prevent formatting mismatches. Additionally, button translations, i.e., presenting a command or request, should be imperative.
## Translating for inclusivity
-TON docs visitors come from all over the world and from different backgrounds. The language on the website should therefore be neutral, welcoming to everyone and not exclusive.
+TON docs visitors come from all over the world and from different backgrounds. Therefore, the language on the website should be neutral, welcoming to everyone, and not exclusive.
-An important aspect of this is gender neutrality. This can be easily achieved by using the formal form of address, and avoiding any gender-specific words in the translations.
+Gender neutrality is an essential aspect of this. Use the formal address form and avoid gender-specific words in the translations.
-Another form of inclusivity is trying to translate for a global audience, not specific to any country, race or region.
+Another form of inclusivity is trying to translate for a global audience, not specific to any country, race, or region.
Finally, the language should be suitable for all audiences and ages.
## Language-specific translations
-When translating, it is important to follow the grammar rules, conventions and formatting, used in your language, as opposed to copying from the source. The source text follows English grammar rules and conventions, which is not applicable to many other languages.
+When translating, it is crucial to follow the grammar rules, conventions, and formatting used in your language instead of copying from the source. The source text follows English grammar rules and conventions, which do not apply to many other languages.
-You should be aware of the rules for your language and translate accordingly. If you need help, reach out to us and we will help you find some resources on how these elements should be used in your language.
+You should be aware of the rules for your language and translate accordingly. If you need help, contact us; we will help you with resources on translating elements for your language.
Some examples of what to be particularly mindful of:
@@ -109,22 +107,22 @@ Some examples of what to be particularly mindful of:
* There are vast differences in capitalization in different languages.
* In English, it is common to capitalize all words in titles and names, months and days, language names, holidays, etc. In many other languages, this is grammatically incorrect, as they have different capitalization rules.
-* Some languages also have rules about capitalizing personal pronouns, nouns, and certain adjectives, which are not capitalized in English.
+* Some languages also have rules about capitalizing personal pronouns, nouns, and adjectives that you shouldn't capitalize in English.
#### Spacing
* Orthography rules define the use of spaces for each language. Because spaces are used everywhere, these rules are some of the most distinct, and spaces are some of the most mistranslated elements.
* Some common differences in spacing between English and other languages:
- * Space before units of measure and currencies (e.g. USD, EUR, kB, MB)
- * Space before degree signs (e.g. °C, ℉)
- * Space before some punctuation marks, especially the ellipsis (…)
- * Space before and after slashes (/)
+ * Space before units of measure and currencies. Example: USD, EUR, kB, MB
+ * Space before degree signs. Example: °C, ℉
+ * Space before some punctuation marks, especially the ellipsis. Example: Then… in summary
+ * Space before and after slashes. Example: if / else
#### Lists
-* Every language has a diverse and complex set of rules for writing lists. These can be significantly different to English.
-* In some languages, the first word of each new line needs to be capitalized, while in others, new lines should start with lower-case letters. Many languages also have different rules about capitalization in lists, depending on the length of each line.
-* The same applies to punctuation of line items. The end punctuation in lists can be a period (.), comma (,), or semicolon (;), depending on the language.
+* Every language has a diverse and complex set of rules for writing lists. These can be significantly different from English.
+* In some languages, the first word of each new line needs to be capitalized, while in others, new lines should start with lowercase letters. Many languages also have different rules about capitalization in lists, depending on the length of each line.
+* The same applies to the punctuation of line items. The end punctuation in lists can be a period (.), comma (,), or semicolon (;), depending on the language.
#### Quotation marks
@@ -139,24 +137,27 @@ Some examples of what to be particularly mindful of:
#### Hyphens and dashes
-* In English, a hyphen (-) is used to join words or different parts of a word, while a dash (–) is used to indicate a range or a pause.
+* In English, a hyphen `-` is used to join words or different parts of a word, while a dash `—` indicates a range or a pause.
+ * Example: TON — is ... proof-of-stake.
* Many languages have different rules for using hyphens and dashes that should be observed.
### Formats
#### Numbers
-* The main difference in writing numbers in different languages is the separator used for decimals and thousands. For thousands, this can be a period, comma or space. Similarly, some languages use a decimal point, while others use a decimal comma.
- * Some examples of large numbers:
+* The main difference in writing numbers in different languages is the separator for decimals and thousands. For thousands, this can be a period, comma, or space. Similarly, some languages use a decimal point, while others use a decimal comma.
+ * Example:
* English – **1,000.50**
* Spanish – **1.000,50**
* French – **1 000,50**
-* Another important consideration when translating numbers is the percent sign. It can be written in different ways: **100%**, **100 %** or **%100**.
-* Finally, negative numbers can be displayed differently, depending on the language: -100, 100-, (100) or [100].
+* The percent sign is another critical consideration when translating numbers. Write numbers in the typical format for the corresponding language.
+ * Example: **100%**, **100 %**, or **%100**.
+* Finally, negative numbers can be displayed differently, depending on the language
+ * Example: -100, 100-, (100) or [100].
#### Dates
-* When translating dates, there are a number of considerations and differences based on the language. These include the date format, separator, capitalization and leading zeros. There are also differences between full-length and numerical dates.
+* When translating dates, there are several considerations and differences based on the language. These include the date format, separator, capitalization, and leading zeros. There are also differences between full-length and numerical dates.
* Some examples of different date formats:
* English UK (dd/mm/yyyy) – 1st January, 2022
* English US (mm/dd/yyyy) – January 1st, 2022
@@ -167,7 +168,7 @@ Some examples of what to be particularly mindful of:
#### Currencies
-* Translating currencies can be challenging, due to the different formats, conventions and conversions. As a general rule, please keep currencies the same as the source. You can add your local currency and conversion in brackets, for the benefit of the reader.
+* Translating currencies can be challenging due to the different formats, conventions, and conversions. As a general rule, please keep currencies the same as the source. You can add your local currency and conversion in brackets for the reader's benefit.
* The main differences in writing currencies in different languages include symbol placement, decimal commas vs. decimal points, spacing, and abbreviations vs. symbols.
* Symbol placement: $100 or 100$
* Decimal commas vs. decimal points: 100,50$ or 100.50$
@@ -176,11 +177,11 @@ Some examples of what to be particularly mindful of:
#### Units of measure
-* As a general rule, please keep the units of measure as per the source. If your country uses a different system, you can include the conversion in brackets.
-* Aside from the localization of units of measure, it is also important to note the differences in how languages approach these units. The main difference is the spacing between the number and unit, which can be different, based on the language. Examples of this include 100kB vs. 100 kB or 50ºF vs. 50 ºF.
+* As a general rule, please keep the units of measure as per the source. You can include the conversion in brackets if your country uses a different system.
+* Aside from the localization of units of measure, it is also important to note the differences in how languages approach these units. The main difference is the spacing between the number and unit, which can differ based on the language. Examples of this include 100kB vs. 100 kB or 50ºF vs. 50 ºF.
## Conclusion
When translating, try not to rush. Take it easy and have fun!
-Thank you for being involved with the Translation Program and helping us make the website accessible to a wider audience. The TON community is global, and we are happy you are a part of it!
\ No newline at end of file
+Thank you for helping us localize the website and make it accessible to a wider audience. The TON community is global, and we are happy you are a part of it!