From 09a72cd638069ea29b8f7e3df888a9360fd74f8e Mon Sep 17 00:00:00 2001 From: Michael Naumov Date: Tue, 11 Nov 2025 15:53:04 -0600 Subject: [PATCH 1/6] docs: add Language section --- en/Plugins/Releasing/Plugin guidelines.md | 25 +++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/en/Plugins/Releasing/Plugin guidelines.md b/en/Plugins/Releasing/Plugin guidelines.md index 7516a3d9..cc67f4e3 100644 --- a/en/Plugins/Releasing/Plugin guidelines.md +++ b/en/Plugins/Releasing/Plugin guidelines.md @@ -376,3 +376,28 @@ async function AsyncTest(): Promise { } } ``` + +## Language + +### English-first + +Write the following in English by default: + +- `id` property in `manifest.json` +- `name` property in `manifest.json` +- `description` property in `manifest.json` +- `README.md` + +You may append translations to each property (except `id`) and document, but the English version must appear first. + +### UI localization + +Set English as the default language for your plugin UI whenever possible. + +Do not mix multiple languages within the same UI. + +If your plugin offers localized UI strings, ensure it respects [`getLanguage()`](https://docs.obsidian.md/Reference/TypeScript+API/getLanguage). + +Don't add a custom language setting to your plugin; rely on Obsidian's built-in language setting instead. + +If your plugin ships without English support, call this out explicitly in both the `description` key in `manifest.json` and the `README.md`. From 0e6ac3390a45205fe5682807ab63f2ae351fc5ba Mon Sep 17 00:00:00 2001 From: Michael Naumov Date: Tue, 11 Nov 2025 19:15:49 -0600 Subject: [PATCH 2/6] docs: rephrase, add Internationalization frameworks --- en/Plugins/Releasing/Plugin guidelines.md | 38 ++++++++++++++++++++--- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/en/Plugins/Releasing/Plugin guidelines.md b/en/Plugins/Releasing/Plugin guidelines.md index cc67f4e3..9eeebde3 100644 --- a/en/Plugins/Releasing/Plugin guidelines.md +++ b/en/Plugins/Releasing/Plugin guidelines.md @@ -383,12 +383,13 @@ async function AsyncTest(): Promise { Write the following in English by default: -- `id` property in `manifest.json` -- `name` property in `manifest.json` -- `description` property in `manifest.json` +- `manifest.json` + - `id` + - `name` + - `description` - `README.md` -You may append translations to each property (except `id`) and document, but the English version must appear first. +It is not recommended but if you really need it, you may include translations (except for `id`), but the English version must appear first. ### UI localization @@ -396,8 +397,35 @@ Set English as the default language for your plugin UI whenever possible. Do not mix multiple languages within the same UI. -If your plugin offers localized UI strings, ensure it respects [`getLanguage()`](https://docs.obsidian.md/Reference/TypeScript+API/getLanguage). +If your plugin offers localized UI strings, ensure it respects [`getLanguage()`](https://docs.obsidian.md/Reference/TypeScript+API/getLanguage) (require `minAppVersion` to be at least `1.8.7`). Don't add a custom language setting to your plugin; rely on Obsidian's built-in language setting instead. If your plugin ships without English support, call this out explicitly in both the `description` key in `manifest.json` and the `README.md`. + +### Internationalization frameworks + +If your plugin supports multiple UI languages, consider using frameworks like [i18next](https://www.i18next.com/), or hand-written one, e.g.: + +```ts +// locales/en.ts +export const en = { + 'some.key': 'Some value' +}; + +// your plugin +import en from './locales/en.ts'; +import zhCN from './locales/zh_CN.ts' +import { getLanguage } from 'obsidian'; + +const localeMap: { [locale: string]: Partial } = { + en: en + zh: zhCN +}; + +const userLocale = localeMap[getLanguage()]; + +export default function t(key: keyof typeof en): string { + return userLocale?.[key] ?? en[key] ?? key; +} +``` From 36fa24595746560453d7bce221f626b1bb1842aa Mon Sep 17 00:00:00 2001 From: Michael Naumov Date: Tue, 11 Nov 2025 19:18:06 -0600 Subject: [PATCH 3/6] docs: usage example --- en/Plugins/Releasing/Plugin guidelines.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/en/Plugins/Releasing/Plugin guidelines.md b/en/Plugins/Releasing/Plugin guidelines.md index 9eeebde3..1c945766 100644 --- a/en/Plugins/Releasing/Plugin guidelines.md +++ b/en/Plugins/Releasing/Plugin guidelines.md @@ -413,7 +413,7 @@ export const en = { 'some.key': 'Some value' }; -// your plugin +// i18n.ts import en from './locales/en.ts'; import zhCN from './locales/zh_CN.ts' import { getLanguage } from 'obsidian'; @@ -425,7 +425,12 @@ const localeMap: { [locale: string]: Partial } = { const userLocale = localeMap[getLanguage()]; -export default function t(key: keyof typeof en): string { +export function t(key: keyof typeof en): string { return userLocale?.[key] ?? en[key] ?? key; } + +// main.ts +import { t } from './i18.ts'; + +new Notice(t('some.key')); ``` From 5a88595489e5871f453a4f0d13f90e6a8e33c3ef Mon Sep 17 00:00:00 2001 From: Michael Naumov Date: Tue, 11 Nov 2025 19:20:34 -0600 Subject: [PATCH 4/6] docs: rephrase --- en/Plugins/Releasing/Plugin guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/Plugins/Releasing/Plugin guidelines.md b/en/Plugins/Releasing/Plugin guidelines.md index 1c945766..301d18d9 100644 --- a/en/Plugins/Releasing/Plugin guidelines.md +++ b/en/Plugins/Releasing/Plugin guidelines.md @@ -401,7 +401,7 @@ If your plugin offers localized UI strings, ensure it respects [`getLanguage()`] Don't add a custom language setting to your plugin; rely on Obsidian's built-in language setting instead. -If your plugin ships without English support, call this out explicitly in both the `description` key in `manifest.json` and the `README.md`. +If your plugin ships without English support, call this out explicitly in both the `description` property in `manifest.json` and the `README.md`. ### Internationalization frameworks From 58c656b9be411df795f731d9306d15530df46a01 Mon Sep 17 00:00:00 2001 From: Michael Naumov Date: Wed, 12 Nov 2025 08:28:33 -0600 Subject: [PATCH 5/6] docs: add i18n --- en/Plugins/Releasing/Plugin guidelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/Plugins/Releasing/Plugin guidelines.md b/en/Plugins/Releasing/Plugin guidelines.md index 301d18d9..095d48b1 100644 --- a/en/Plugins/Releasing/Plugin guidelines.md +++ b/en/Plugins/Releasing/Plugin guidelines.md @@ -403,7 +403,7 @@ Don't add a custom language setting to your plugin; rely on Obsidian's built-in If your plugin ships without English support, call this out explicitly in both the `description` property in `manifest.json` and the `README.md`. -### Internationalization frameworks +### Internationalization (i18n) frameworks If your plugin supports multiple UI languages, consider using frameworks like [i18next](https://www.i18next.com/), or hand-written one, e.g.: @@ -430,7 +430,7 @@ export function t(key: keyof typeof en): string { } // main.ts -import { t } from './i18.ts'; +import { t } from './i18n.ts'; new Notice(t('some.key')); ``` From 8eda954fd6bb9d1e0fbd7df2343c6fcbf9b519e8 Mon Sep 17 00:00:00 2001 From: Michael Naumov Date: Wed, 12 Nov 2025 08:30:45 -0600 Subject: [PATCH 6/6] docs: fix grammar --- en/Plugins/Releasing/Plugin guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/Plugins/Releasing/Plugin guidelines.md b/en/Plugins/Releasing/Plugin guidelines.md index 095d48b1..003dac26 100644 --- a/en/Plugins/Releasing/Plugin guidelines.md +++ b/en/Plugins/Releasing/Plugin guidelines.md @@ -397,7 +397,7 @@ Set English as the default language for your plugin UI whenever possible. Do not mix multiple languages within the same UI. -If your plugin offers localized UI strings, ensure it respects [`getLanguage()`](https://docs.obsidian.md/Reference/TypeScript+API/getLanguage) (require `minAppVersion` to be at least `1.8.7`). +If your plugin offers localized UI strings, ensure it respects [`getLanguage()`](https://docs.obsidian.md/Reference/TypeScript+API/getLanguage) (requires `minAppVersion` to be at least `1.8.7`). Don't add a custom language setting to your plugin; rely on Obsidian's built-in language setting instead.