ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-04 11:55:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update translation contribution docs (fix #3239)

Browse Source
This commit is contained in:
mDuo13
2025-10-20 17:53:19 -07:00
parent b1c8a33de9
commit d7ca624269
1 changed files with 39 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

97
resources/contribute-documentation/documentation-translations.md
View File

@@ -1,81 +1,62 @@
--- ---
html: documentation-translations.html
parent: contribute-documentation.html
seo: seo:
description: Learn how to contribute and maintain translations of the documentation on this website. description: Learn how to contribute and maintain translations of the documentation on this website.
--- ---
# Translations # Translations
The XRP Ledger Dev Portal is mostly written in English, so the English version is generally the most up-to-date and accurate version. However, to broaden the reach of the XRP Ledger software and community, this repository also contains translated versions of the documentation. We strongly encourage members of the community who understand other languages to contribute translations of the dev portal contents in their native languages. The XRP Ledger Dev Portal (XRPL.org) is mostly written in English, so the English version is generally the most up-to-date and accurate version. However, to broaden the reach of the XRP Ledger software and community, this repository also contains translated versions of the documentation. We strongly encourage members of the community who understand other languages to contribute translations of the dev portal contents in their native languages.
The `dactyl-config.yml` contains a "target" entry for each available language. (Currently, the available languages are English and Japanese.) This entry includes a dictionary of strings used in the template files. For example: The languages currently provided are:
```yaml | Language | Code | Status |
- name: en |-------------------|------|--------|
lang: en | English | (N/A) | Primary language, with most work and updates being done in English first. |
display_name: XRP Ledger Dev Portal | Japanese (日本語) | `ja` | Available on the site. Maintained on a best-effort basis, but sometimes not as up-to-date as the English version. |
# These github_ fields are used by the template's "Edit on GitHub" link. | Spanish (Español) | `es-ES` | Incomplete, not actively maintained. Not currently served on the production site. |
# Override them with --vars to change which fork/branch to edit.
github_forkurl: https://github.com/XRPLF/xrpl-dev-portal
github_branch: master
strings:
blog: "Blog"
search: "Search site with Google..."
bc_home: "Home"
# ...
```
There is also a top-level `languages` listing that defines some properties for each supported language. The short code for each language should be short code according to [IETF BCP47](https://tools.ietf.org/html/bcp47). For example, "en" for English, "es" for Spanish, "ja" for Japanese, "zh-CN" for Simplified Chinese, "zh-TW" for Traditional Chinese (as used in Taiwan), and so on. The `display_name` field defines the language's name as written natively in that language. The `prefix` field defines a prefix to be used in hyperlinks to that language's version of the site. Example `languages` definition:
```yaml
languages:
- code: en
display_name: English
prefix: "/"
- code: ja
display_name: 日本語
prefix: "/ja/"
```
The same `dactyl-config.yml` file contains an entry for each content page in the XRP Ledger Dev Portal. If a page has been translated, there is a separate entry for each translation, linked to the "target" for that translation. If a page has not yet been translated, the English version is used across all targets. (If a new page is added only to English and not other languages, the link checker reports that as a broken link.)
Translating a page means separating out the entry for that page in the other language. Here are some tips for translating the page's metadata, which can be in either the `dactyl-config.yml` file or the frontmatter at the top of the page's Markdown file:
| Field | Notes |
|-------|-------|
| `html` | The HTML file name of the page. By convention, this should be the same across all language versions. |
| `md` | The Markdown source file for the page. Translated Markdown source files should use the same filename as the English-language version except that the file extension should be `.{language code}.md` instead of only `.md` for English. For example, Japanese translated files end in `.ja.md`. |
| `blurb` | A short summary of the page. This should be translated. This text is used in metadata for search engine optimization and also on automatically-generated landing pages. |
Example of English and Japanese entries for the `server_info` method page: ## Translations Folder
```yaml The `@l10n` folder of the repository contains the translated docs for the site, including documentation pages (written in Markdown) and non-documentation pages such as dev tools that use the translations file to replace smaller strings of text where possible. Each translation exists in a separate folder identified by an [IETF BCP47](https://tools.ietf.org/html/bcp47) language code. Within the folder for a given language, the folder structure mirrors the top of the repository, such that content files whose path matches exactly are used instead of the English language versions. For example, `@l10n/ja/docs/concepts/accounts/index.md` is a Japanese-translated version of `docs/concepts/accounts/index.md`.
- md: references/http-websocket-apis/public-api-methods/server-info-methods/server_info.md
targets:
- en
- md: references/http-websocket-apis/public-api-methods/server-info-methods/server_info.ja.md If there is not a parallel version of a file in the translation folder, the English version displays when you navigate to that page on the translated version of the site.
targets:
- ja
```
Example entry for a page that isn't translated:
```yaml ## Strings File
- md: concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md
targets: The `translations.yaml` file contains strings of text that are used in specially-stylized pages (with the `.page.tsx` extension) including dev tools and the "marketing" pages in the `about/` and `community/` sections of the site, and in some cases the `sidebars.yaml` file too.
- en
- ja Preferably, strings should use a key such as `topnav.docs.tutorials` to uniquely indicate the text being translated. Strings can also be matched by exactly the English text being translated, but matching by the English text is not ideal because the same text may need to be translated differently based on context, or different segments of text may need to be translated non-exactly to display correctly. The original files should be updated to use translation keys as needed.
```
## Moving or Renaming Files
When files are moved or renamed, the translated files also need to be moved or renamed the same way.
When you add redirects to the `redirects.yaml` file at the repository top, also add redirects for each translation (these are grouped later in the file).
## Where to Start ## Where to Start
If you want to translate the XRP Ledger Dev Portal into your native language of choice, start with the {% repo-link path="docs/concepts/introduction/what-is-the-xrp-ledger.md" %}"What is the XRP Ledger?" page{% /repo-link %}, which introduces the core concepts behind the XRP Ledger. If you want to translate the XRP Ledger Dev Portal into your native language of choice, start with the {% repo-link path="docs/introduction/what-is-the-xrp-ledger.md" %}"What is the XRP Ledger?" page{% /repo-link %}, which introduces the core concepts behind the XRP Ledger.
Save the file as `what-is-the-xrp-ledger.{language code}.md`, where `{language code}` is the [IETF BCP47](https://tools.ietf.org/html/bcp47) language code. (For example, "es" for Spanish, "ja" for Japanese, "zh-CN" for Simplified Chinese, "zh-TW" for Traditional Chinese as used in Taiwan, and so on.) Then open a [pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) adding your file to this repository. One of the repository's maintainers can help with the other necessary setup to add the language to the site. Save the file as `@l10n/{language code}/docs/introduction/what-is-the-xrp-ledger.md`, where `{language code}` is the [IETF BCP47](https://tools.ietf.org/html/bcp47) language code. (For example, "es-ES" for Spanish (Spain), "ja" for Japanese, "zh-CN" for Simplified Chinese, "zh-TW" for Traditional Chinese as used in Taiwan, and so on.) Then open a [pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) adding your file to this repository. One of the repository's maintainers can help with the other necessary setup to add the language to the site.
For the Markdown content files, please use the following conventions: For the Markdown content files, please use the following conventions:
- Line-feed newline characters (`\n`) only (Unix style). Do not use carriage return (`\r`) characters (Windows style). - Line-feed newline characters (`\n`) only (Unix style). Do not use carriage return (`\r`) characters (Windows style).
- Use UTF-8 encoding. Avoid the use of Byte-order marks. - Use UTF-8 encoding. Avoid the use of Byte-order marks.
To test changes with the translated version of the site, modify the `redocly.yaml` file at the repository top and add the language in question to the `l10n.locales` list:
```yaml
l10n:
defaultLocale: en-US
locales:
- code: en-US
name: English
- code: ja
name: 日本語
```
Then start the local dev server with `npm run start` from the repository top, use your web browser to view the local site, and choose the language from the dropdown in the main menu.