docs: add guide on how to translate admin (#10095)
* docs: add guide on how to translate admin * added a link from the main docs
This commit is contained in:
Shahed Nasser
@@ -167,4 +167,12 @@ This adds a widget in a product's details page with a link to the Orders page. T
|
||||
|
||||
Refer to [react-router-dom’s documentation](https://reactrouter.com/en/main) for other available components and hooks.
|
||||
|
||||
</Note>
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Admin Translations
|
||||
|
||||
The Medusa Admin dashboard can be displayed in languages other than English, which is the default. Other languages are added through community contributions.
|
||||
|
||||
Learn how to add a new language translation for the Medusa Admin in [this guide](!resources!/contribution-guidelines/admin-translations).
|
||||
|
||||
@@ -1,49 +0,0 @@
|
||||
export const metadata = {
|
||||
title: `Contribute by Translating Admins`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
The Medusa Admin supports multiple languages, with the default being English. We highly appreciate your contribution by translation to other languages you're fluent with, as it ensures a wider support of languages.
|
||||
|
||||
This type of contribution is a no-code contribution, meaning you don't need advanced technical skills to contribute.
|
||||
|
||||
---
|
||||
|
||||
## How to Contribute Translation
|
||||
|
||||
1. Clone the [Medusa monorepository](https://github.com/medusajs/medusa) to your local machine:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/medusajs/medusa.git
|
||||
```
|
||||
|
||||
If you already have it cloned, make sure to pull the latest changes from the `develop` branch.
|
||||
|
||||
2. Create a branch that'll be used to open the pull request later:
|
||||
|
||||
```bash
|
||||
git check -b feat/translate-<LANGUAGE>
|
||||
```
|
||||
|
||||
Where `<LANGUAGE>` is your language name. For example, `feat/translate-da`.
|
||||
|
||||
3. Create a new directory under `packages/admin-ui/ui/public/locales` with its name being the [ISO 2 character code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) of your language. For example, `da`. In the new directory, create the file `translation.json`.
|
||||
|
||||
4. Copy the content of the English translation file located at `packages/admin-ui/ui/public/locales/en/translation.json` and paste it in your new `translation.json` file.
|
||||
|
||||
5. In the file, leave the key names as-is, and only translate the values.
|
||||
|
||||
7. In the file `packages/admin-ui/ui/src/i18n/index.ts`, add the new language to the `supportedLanguages` array as an object. The object accepts two properties: `locale` for the ISO 2 character code, and `name` for the name of the language. The name of the language should be the translated name, not the English name. For example:
|
||||
|
||||
```ts title="packages/admin-ui/ui/src/i18n/index.ts"
|
||||
export const supportedLanguages = [
|
||||
// other languages...
|
||||
{
|
||||
locale: "da",
|
||||
name: "Dansk",
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
8. Once you're done, push the changes into your branch and open a pull request on GitHub.
|
||||
@@ -0,0 +1,107 @@
|
||||
export const metadata = {
|
||||
title: `Translate Medusa Admin`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
The Medusa Admin supports multiple languages, with the default being English. In this documentation, you'll learn how to contribute to the community by translating the Medusa Admin to a language you're fluent in.
|
||||
|
||||
{/* vale docs.We = NO */}
|
||||
|
||||
You can contribute either by translating the admin to a new language, or fixing translations for existing languages. As we can't validate every language's translations, some translations may be incorrect. Your contribution is welcome to fix any translation errors you find.
|
||||
|
||||
{/* vale docs.We = YES */}
|
||||
|
||||
<Note>
|
||||
|
||||
Check out the translated languages either in the admin dashboard's settings or on [GitHub](https://github.com/medusajs/medusa/blob/develop/packages/admin/dashboard/src/i18n/languages.ts).
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## How to Contribute Translation
|
||||
|
||||
1. Clone the [Medusa monorepository](https://github.com/medusajs/medusa) to your local machine:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/medusajs/medusa.git
|
||||
```
|
||||
|
||||
If you already have it cloned, make sure to pull the latest changes from the `develop` branch.
|
||||
|
||||
2. Install the monorepository's dependencies. Since it's a Yarn workspace, it's highly recommended to use yarn:
|
||||
|
||||
```bash
|
||||
yarn install
|
||||
```
|
||||
|
||||
3. Create a branch that you'll use to open the pull request later:
|
||||
|
||||
```bash
|
||||
git check -b feat/translate-<LANGUAGE>
|
||||
```
|
||||
|
||||
Where `<LANGUAGE>` is your language name. For example, `feat/translate-da`.
|
||||
|
||||
4. Translation files are under `packages/admin/dashboard/src/i18n/translations` as JSON files whose names are the ISO-2 name of the language.
|
||||
- If you're adding a new language, copy the file `packages/admin/dashboard/src/i18n/translations/en.json` and paste it with the ISO-2 name for your language. For example, if you're adding Danish translations, copy the `en.json` file and paste it as `packages/admin/dashboard/src/i18n/translations/de.json`.
|
||||
- If you're fixing a translation, find the JSON file of the language under `packages/admin/dashboard/src/i18n/translations`.
|
||||
|
||||
5. Start translating the keys in the JSON file (or updating the targeted ones). All keys in the JSON file must be translated, and your PR tests will fail otherwise.
|
||||
- You can check whether the JSON file is valid by running the following command in `packages/admin/dashboard`, replacing `da.json` with the JSON file's name:
|
||||
|
||||
```bash title="packages/admin/dashboard"
|
||||
yarn i18n:validate da.json
|
||||
```
|
||||
|
||||
6. After finishing the translation, if you're adding a new language, import its JSON file in `packages/admin/dashboard/src/i18n/translations/index.ts` and add it to the exported object:
|
||||
|
||||
```ts title="packages/admin/dashboard/src/i18n/translations/index.ts" highlights={[["2"], ["6"], ["7"], ["8"]]}
|
||||
// other imports...
|
||||
import da from "./da.json"
|
||||
|
||||
export default {
|
||||
// other languages...
|
||||
da: {
|
||||
translation: da,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
The language's key in the object is the ISO-2 name of the language.
|
||||
|
||||
7. If you're adding a new language, add it to the file `packages/admin/dashboard/src/i18n/languages.ts`:
|
||||
|
||||
export const languageHighlights = [
|
||||
["7", "code", "The ISO-2 name of the language."],
|
||||
["8", "display_name", "The language's name to be displayed in the admin."],
|
||||
["9", "ltr", "Whether the language supports a left-to-right layout."],
|
||||
["10", "date_locale", "An instance of the locale imported from the [date-fns/locale](https://date-fns.org/) package."]
|
||||
]
|
||||
|
||||
```ts title="packages/admin/dashboard/src/i18n/languages.ts" highlights={languageHighlights}
|
||||
import { da } from "date-fns/locale"
|
||||
// other imports...
|
||||
|
||||
export const languages: Language[] = [
|
||||
// other languages...
|
||||
{
|
||||
code: "da",
|
||||
display_name: "Danish",
|
||||
ltr: true,
|
||||
date_locale: da
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
`languages` is an array having the following properties:
|
||||
|
||||
- `code`: The ISO-2 name of the language. For example, `da` for Danish.
|
||||
- `display_name`: The language's name to be displayed in the admin.
|
||||
- `ltr`: Whether the language supports a left-to-right layout. For example, set this to `false` for languages like Arabic.
|
||||
- `date_locale`: An instance of the locale imported from the [date-fns/locale](https://date-fns.org/) package.
|
||||
|
||||
8. Once you're done, push the changes into your branch and open a pull request on GitHub.
|
||||
|
||||
Our team will perform a general review on your PR and merge it if no issues are found. The translation will be available in the admin after the next release.
|
||||
@@ -113,7 +113,6 @@ export const generatedEditDates = {
|
||||
"app/commerce-modules/user/user-creation-flows/page.mdx": "2024-10-15T14:51:37.311Z",
|
||||
"app/commerce-modules/user/page.mdx": "2024-10-15T14:44:19.628Z",
|
||||
"app/commerce-modules/page.mdx": "2024-10-07T13:55:08.014Z",
|
||||
"app/contribution-guidelines/_admin-translations/page.mdx": "2024-05-13T18:55:11+03:00",
|
||||
"app/contribution-guidelines/docs/page.mdx": "2024-10-16T15:48:04.071Z",
|
||||
"app/create-medusa-app/page.mdx": "2024-08-05T11:10:55+03:00",
|
||||
"app/deployment/admin/vercel/page.mdx": "2024-10-16T08:10:29.377Z",
|
||||
@@ -3251,5 +3250,6 @@ export const generatedEditDates = {
|
||||
"references/types/types/types.UncountableRules/page.mdx": "2024-11-12T09:36:21.340Z",
|
||||
"references/product/interfaces/product.FilterableProductProps/page.mdx": "2024-11-12T09:36:53.124Z",
|
||||
"references/types/HttpTypes/interfaces/types.HttpTypes.AdminBatchProductVariantRequest/page.mdx": "2024-11-12T09:36:22.780Z",
|
||||
"references/types/WorkflowTypes/ProductWorkflow/interfaces/types.WorkflowTypes.ProductWorkflow.ExportProductsDTO/page.mdx": "2024-11-12T09:36:24.232Z"
|
||||
"references/types/WorkflowTypes/ProductWorkflow/interfaces/types.WorkflowTypes.ProductWorkflow.ExportProductsDTO/page.mdx": "2024-11-12T09:36:24.232Z",
|
||||
"app/contribution-guidelines/admin-translations/page.mdx": "2024-11-14T08:54:15.369Z"
|
||||
}
|
||||
@@ -556,8 +556,8 @@ export const filesMap = [
|
||||
"pathname": "/commerce-modules/user/user-creation-flows"
|
||||
},
|
||||
{
|
||||
"filePath": "/www/apps/resources/app/contribution-guidelines/_admin-translations/page.mdx",
|
||||
"pathname": "/contribution-guidelines/_admin-translations"
|
||||
"filePath": "/www/apps/resources/app/contribution-guidelines/admin-translations/page.mdx",
|
||||
"pathname": "/contribution-guidelines/admin-translations"
|
||||
},
|
||||
{
|
||||
"filePath": "/www/apps/resources/app/contribution-guidelines/docs/page.mdx",
|
||||
|
||||
@@ -14925,6 +14925,14 @@ export const generatedSidebar = [
|
||||
"path": "/contribution-guidelines/docs",
|
||||
"title": "Docs",
|
||||
"children": []
|
||||
},
|
||||
{
|
||||
"loaded": true,
|
||||
"isPathHref": true,
|
||||
"type": "link",
|
||||
"path": "/contribution-guidelines/admin-translations",
|
||||
"title": "Admin Translations",
|
||||
"children": []
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@@ -2104,12 +2104,12 @@ export const sidebar = sidebarAttachHrefCommonOptions([
|
||||
{
|
||||
type: "link",
|
||||
path: "https://docs.medusajs.com/learn/deployment/general",
|
||||
title: "General"
|
||||
title: "General",
|
||||
},
|
||||
{
|
||||
type: "link",
|
||||
path: "/deployment/medusa-application/railway",
|
||||
title: "Railway"
|
||||
title: "Railway",
|
||||
},
|
||||
],
|
||||
},
|
||||
@@ -2393,10 +2393,11 @@ export const sidebar = sidebarAttachHrefCommonOptions([
|
||||
path: "/contribution-guidelines/docs",
|
||||
title: "Docs",
|
||||
},
|
||||
// {
|
||||
// path: "/contribution-guidelines/admin-translations",
|
||||
// title: "Admin Translations",
|
||||
// },
|
||||
{
|
||||
type: "link",
|
||||
path: "/contribution-guidelines/admin-translations",
|
||||
title: "Admin Translations",
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user