i18n(ru): update some guides and references (#2333)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

docs/src/content/docs/ru/guides/i18n.mdx

@@ -277,6 +277,118 @@ export const collections = {
 
 Дополнительную информацию о схемах коллекции контента см. в разделе [Определение схемы коллекции](https://docs.astro.build/ru/guides/content-collections/#%D0%BE%D0%BF%D1%80%D0%B5%D0%B4%D0%B5%D0%BB%D0%B5%D0%BD%D0%B8%D0%B5-%D1%81%D1%85%D0%B5%D0%BC%D1%8B-%D0%BA%D0%BE%D0%BB%D0%BB%D0%B5%D0%BA%D1%86%D0%B8%D0%B8) в документации Astro.
 
+## Использование переводов пользовательского интерфейса
+
+Вы можете получить доступ к [встроенным строкам пользовательского интерфейса](/ru/guides/i18n/#перевод-интерфейса-starlight) Starlight, а также к [пользовательским](/ru/guides/i18n/#расширение-схемы-перевода) и [предоставляемым плагинами](/ru/reference/plugins/#injecttranslations) строкам пользовательского интерфейса через единый API на базе [i18next](https://www.i18next.com/).
+Это включает поддержку таких функций, как [интерполяция](https://www.i18next.com/translation-function/interpolation) и [плюрализация](https://www.i18next.com/translation-function/plurals).
+
+В компонентах Astro этот API доступен как часть [глобального объекта `Astro`](https://docs.astro.build/ru/reference/api-reference/#astrolocals) в виде `Astro.locals.t`:
+
+```astro title="example.astro"
+<p dir={Astro.locals.t.dir()}>
+  {Astro.locals.t('404.text')}
+</p>
+```
+
+Вы также можете использовать API в [эндпойнтах](https://docs.astro.build/ru/guides/endpoints/), где объект `locals` доступен как часть контекста [эндпойнта](https://docs.astro.build/ru/reference/api-reference/#contextlocals):
+
+```ts title="src/pages/404.ts"
+export const GET = (context) => {
+  return new Response(context.locals.t('404.text'));
+};
+```
+
+### Рендеринг строки пользовательского интерфейса
+
+Отрисовка строк пользовательского интерфейса с помощью функции `locals.t()`.
+Это экземпляр функции i18next `t()`, которая принимает в качестве первого аргумента строку-ключ UI и возвращает соответствующий перевод для текущего языка.
+
+Например, задан файл пользовательского перевода со следующим содержанием:
+
+```json title="src/content/i18n/ru.json"
+{
+  "link.astro": "Документация Astro",
+  "link.astro.custom": "Документация Astro о {{feature}}"
+}
+```
+
+Первую строку пользовательского интерфейса можно отобразить, передав `'link.astro'` в функцию `t()`:
+
+```astro {3}
+<!-- src/components/Example.astro -->
+<a href="https://docs.astro.build/">
+  {Astro.locals.t('link.astro')}
+</a>
+<!-- Отрисовывает: <a href="...">Документация Astro</a> -->
+```
+
+Вторая строка пользовательского интерфейса использует [синтаксис интерполяции](https://www.i18next.com/translation-function/interpolation) i18next для размещения `{{feature}}`.
+Значение для `feature` должно быть задано в объекте options, передаваемом в качестве второго аргумента в `t()`:
+
+```astro {3}
+<!-- src/components/Example.astro -->
+<a href="https://docs.astro.build/ru/guides/astro-db/">
+  {Astro.locals.t('link.astro.custom', { feature: 'Astro DB' })}
+</a>
+<!-- Отрисовывает: <a href="...">Документация Astro о Astro DB</a> -->
+```
+
+Подробнее о том, как использовать функцию `t()` для интерполяции, форматирования и т. д., см. в [документации i18next](https://www.i18next.com/overview/api#t).
+
+### Расширенные API
+
+#### `t.all()`
+
+Функция `locals.t.all()` возвращает объект, содержащий все строки пользовательского интерфейса, доступные для текущей локали.
+
+```astro
+---
+// src/components/Example.astro
+const allStrings = Astro.locals.t.all();
+//    ^
+//    {
+//      "skipLink.label": "Перейти к содержанию",
+//      "search.label": "Поиск",
+//      …
+//    }
+---
+```
+
+#### `t.exists()`
+
+Чтобы проверить, существует ли ключ перевода для локали, используйте функцию `locals.t.exists()` с ключом перевода в качестве первого аргумента.
+Передайте необязательный второй аргумент, если вам нужно переопределить текущую локаль.
+
+```astro
+---
+// src/components/Example.astro
+const keyExistsInCurrentLocale = Astro.locals.t.exists('a.key');
+//    ^ true
+const keyExistsInFrench = Astro.locals.t.exists('another.key', { lng: 'fr' });
+//    ^ false
+---
+```
+
+Дополнительную информацию см. в статье [`exists()` в документации i18next](https://www.i18next.com/overview/api#exists).
+
+#### `t.dir()`
+
+Функция `locals.t.dir()` возвращает направление текста текущей или определённой локали.
+
+```astro
+---
+// src/components/Example.astro
+const currentDirection = Astro.locals.t.dir();
+//    ^
+//    'ltr'
+const arabicDirection = Astro.locals.t.dir('ar');
+//    ^
+//    'rtl'
+---
+```
+
+Дополнительную информацию см. в статье [`dir()` в документации i18next](https://www.i18next.com/overview/api#dir).
+
 ## Доступ к текущей локали
 
 Вы можете использовать [`Astro.currentLocale`](https://docs.astro.build/ru/reference/api-reference/#astrocurrentlocale) для получения текущей локали в компонентах `.astro`.

docs/src/content/docs/ru/guides/sidebar.mdx

@@ -520,6 +520,52 @@ starlight({
 На многоязычных сайтах значение `slug` не включает языковую часть URL.
 Например, если у вас есть страницы `en/intro` и `pt-br/intro`, при настройке боковой панели в качестве slug будет `intro`.
 
+### Интернационализация с помощью значков
+
+Для [значков](#значки) свойство `text` может быть строкой, а для многоязычных сайтов — объектом со значениями для каждой локали.
+При использовании объектной формы ключи должны быть тегами [BCP-47](https://www.w3.org/International/questions/qa-choosing-language-tags) (например: `en`, `ar` или `zh-CN`):
+
+```js {11-16}
+starlight({
+	sidebar: [
+		{
+			label: 'Созвездия',
+			translations: {
+				'pt-BR': 'Constelações',
+			},
+			items: [
+				{
+					slug: 'constellations/andromeda',
+					badge: {
+						text: {
+							ru: 'Новинка',
+							'pt-BR': 'Novo',
+						},
+					},
+				},
+			],
+		},
+	],
+});
+```
+
+При просмотре документации на бразильском португальском языке появится следующая боковая панель:
+
+<SidebarPreview
+	config={[
+		{
+			label: 'Constelações',
+			items: [
+				{
+					label: 'Andrômeda',
+					link: '',
+					badge: { text: 'Novo', variant: 'default' },
+				},
+			],
+		},
+	]}
+/>
+
 ## Сворачиваемые группы
 
 Группы ссылок могут быть свёрнуты по умолчанию, если установить свойство `collapsed` в `true`.

docs/src/content/docs/ru/reference/overrides.md

@@ -148,12 +148,6 @@ entry: {
 
 Объект `URL` для адреса, по которому можно редактировать данную страницу, если это разрешено.
 
-#### `labels`
-
-**тип:** `Record<string, string>`
-
-Объект, содержащий строки пользовательского интерфейса, локализованные для текущей страницы. Список всех доступных ключей см. в разделе [Перевод интерфейса Starlight](/ru/guides/i18n/#перевод-интерфейса-starlight).
-
 ---
 
 ## Компоненты

docs/src/content/docs/ru/reference/plugins.md

@@ -27,6 +27,7 @@ interface StarlightPlugin {
       command: 'dev' | 'build' | 'preview';
       isRestart: boolean;
       logger: AstroIntegrationLogger;
+      injectTranslations: (Record<string, Record<string, string>>) => void;
     }) => void | Promise<void>;
   };
 }
@@ -161,3 +162,71 @@ export default {
 ```shell
 [long-process-plugin] Начало длительного процесса...
 ```
+
+#### `injectTranslations`
+
+**тип:** `(translations: Record<string, Record<string, string>>) => void`
+
+Функция обратного вызова для добавления или обновления строк перевода, используемых в [API локализации](/ru/guides/i18n/#использование-переводов-пользовательского-интерфейса) Starlight.
+
+В следующем примере плагин инжектирует переводы для пользовательской строки пользовательского интерфейса с именем `myPlugin.doThing` для локалей `en` и `ru`:
+
+```ts {6-13} /(injectTranslations)[^(]/
+// plugin.ts
+export default {
+  name: 'plugin-with-translations',
+  hooks: {
+    setup({ injectTranslations }) {
+      injectTranslations({
+        en: {
+          'myPlugin.doThing': 'Do the thing',
+        },
+        ru: {
+          'myPlugin.doThing': 'Делай дело',
+        },
+      });
+    },
+  },
+};
+```
+
+Чтобы использовать инжектированные переводы в пользовательском интерфейсе плагина, следуйте руководству [Использование переводов пользовательского интерфейса](/ru/guides/i18n/#использование-переводов-пользовательского-интерфейса).
+
+Типы для инжектируемых строк перевода плагина генерируются автоматически в проекте пользователя, но ещё не доступны при работе с кодовой базой вашего плагина.
+Чтобы ввести объект `locals.t` в контексте вашего плагина, объявите следующие глобальные пространства имён в файле декларации TypeScript:
+
+```ts
+// env.d.ts
+declare namespace App {
+  type StarlightLocals = import('@astrojs/starlight').StarlightLocals;
+  // Определяем объект `locals.t` в контексте плагина.
+  interface Locals extends StarlightLocals {}
+}
+
+declare namespace StarlightApp {
+  // Определяем дополнительные переводы плагинов в интерфейсе `I18n`.
+  interface I18n {
+    'myPlugin.doThing': string;
+  }
+}
+```
+
+Вы также можете определить типы интерфейса `StarlightApp.I18n` из исходного файла, если у вас есть объект, содержащий ваши переводы.
+
+Например, учитывая следующий исходный файл:
+
+```ts title="ui-strings.ts"
+export const UIStrings = {
+  en: { 'myPlugin.doThing': 'Do the thing' },
+  ru: { 'myPlugin.doThing': 'Делай дело' },
+};
+```
+
+Следующее объявление будет определять типы по английским ключам в исходном файле:
+
+```ts title="env.d.ts"
+declare namespace StarlightApp {
+  type UIStrings = typeof import('./ui-strings').UIStrings.en;
+  interface I18n extends UIStrings {}
+}
+```