|
| 1 | +# Процесс локализации |
| 2 | +## Локализация |
| 3 | +### Создание языкового пакета |
| 4 | +В Material Docs присутствует встроенный механизм для локализации. Языковой пакет имеет следующую структуру: |
| 5 | +* Lang |
| 6 | + * ```name: string``` - Название языкового пакета. (_рекомендует называть в соответствии со стандартами, например __en-us___) |
| 7 | + * ```label: string``` - Красивое названия языкового пакета, будет отображено в интерфейсе. |
| 8 | + * ```locale: abject``` - Объект, в котором хранятся ваши данные о локализации. |
| 9 | + * ```loadLang(): object``` - Функция, которая будет вызвана при загрузке языка. Нужна для получения локализации с удаленного хоста. |
| 10 | + |
| 11 | +> В объекте Lang __обязательно должен быть определен один из параметров: _locale_ или _loadLang_!__ |
| 12 | +
|
| 13 | +Создадим языковой пакет для существующих страниц и передадим его в ```<DocsLayout/>```: |
| 14 | +##### locale/EN.js |
| 15 | +``` |
| 16 | +export default { |
| 17 | + name: "en-us", |
| 18 | + label: "English", |
| 19 | + locale: { |
| 20 | + pages: { |
| 21 | + FirstPage: { |
| 22 | + header1: "My name is Danil Andreev", |
| 23 | + header2: "This is a page about my history.", |
| 24 | + text: "Hello, my name is __Danil Andreev__, I am a programmer from Kiev, Ukraine.", |
| 25 | + header3: "I will show you a piece of code", |
| 26 | + }, |
| 27 | + SecondPage: { |
| 28 | + header1: "This is a feature page", |
| 29 | + header2: "Table", |
| 30 | + redirect: "Redirect to Page About Me", |
| 31 | + } |
| 32 | + } |
| 33 | + } |
| 34 | +} |
| 35 | +``` |
| 36 | +Теперь, когда мы создали один языковой пакет, мы можем запустить систему локализации Material Docs. Для этого |
| 37 | +нужно передать пакет в ```<DocsLayout/>```: |
| 38 | +``` |
| 39 | +<DocsLayout |
| 40 | + name={"My documentation"} |
| 41 | + version={"1.0.0-alpha"} |
| 42 | + logo={"http://material-docs.com/static/media/logo.5a237c82.svg"} |
| 43 | + keywords={["my", "test", "documentation"]} |
| 44 | + description={"This is an example documentation for Material Docs framework."} |
| 45 | + author={"Danil Andreev"} |
| 46 | +
|
| 47 | + defaultLang={EN} |
| 48 | +> |
| 49 | +{/*...*/} |
| 50 | +</DocsLayout> |
| 51 | +``` |
| 52 | +В правом верхнем углу появилось поле с языком. |
| 53 | +### Доступ к языковому пакету |
| 54 | +Теперь, давайте достанем текст из языкового пакета. Для этого воспользуемся компонентом ```<Locale/>```. В параметре ___path___ |
| 55 | + указывается путь к переменной внутри объекта _locale_ в языковом пакете. |
| 56 | +> Обратите внимание, локализацию компонента ```<Markdown/>``` нужно проводить иначе. В этом компоненте присутствует |
| 57 | +> собственный параметр ___locale___, с помощью которого мы советуем указывать путь в языковом пакете. |
| 58 | +
|
| 59 | +``` |
| 60 | +import React from "react"; |
| 61 | +import DocsPage from "@material-docs/core/components/DocsPage"; |
| 62 | +import H1 from "@material-docs/core/components/H1"; |
| 63 | +import H3 from "@material-docs/core/components/H3"; |
| 64 | +import Markdown from "@material-docs/core/components/Markdown"; |
| 65 | +import Image from "@material-docs/core/components/Image"; |
| 66 | +import H4 from "@material-docs/core/components/H4"; |
| 67 | +import Code from "@material-docs/core/components/Code"; |
| 68 | +import Locale from "@material-docs/core/components/Locale"; |
| 69 | +
|
| 70 | +const image = "https://cdnb.artstation.com/p/users/avatars/000/449/963/large/fc6a568b26ecfe1fe02f6dc60da732ae.jpg?1587936613"; |
| 71 | +
|
| 72 | +export default function FirstPage() { |
| 73 | + return ( |
| 74 | + <DocsPage |
| 75 | + name={"Page about me"} |
| 76 | + searchLabel={"Danil Andreev | About me"} |
| 77 | + searchDescription={"This is a page about my person."} |
| 78 | + searchTags={["me", "info", "danil", "andreev", "programmer"]} |
| 79 | + > |
| 80 | + <H1><Locale path={"pages/FirstPage/header1"}/></H1> |
| 81 | + <H3><Locale path={"pages/FirstPage/header2"}/></H3> |
| 82 | + <Markdown locale={"pages/FirstPage/text"} /> |
| 83 | + <Image src={image}/> |
| 84 | + <H4><Locale path={"pages/FirstPage/header3"}/></H4> |
| 85 | + <Code> |
| 86 | + $ Hello darkness my old friend |
| 87 | + </Code> |
| 88 | + </DocsPage> |
| 89 | +
|
| 90 | + ); |
| 91 | +} |
| 92 | +``` |
| 93 | +### Добавление перевода |
| 94 | +После того, как мы создали ___defaultLanguage___, можно переходить к переводу. |
| 95 | +> Используйте только те поля, которые указаны в поле ___locale___ __языкового пакета по умолчанию__. |
| 96 | +
|
| 97 | +Создадим перевод: |
| 98 | +``` |
| 99 | +export default { |
| 100 | + name: "ru-ru", |
| 101 | + label: "Русский", |
| 102 | + locale: { |
| 103 | + pages: { |
| 104 | + FirstPage: { |
| 105 | + header1: "Моё имя Данил Андреев", |
| 106 | + header3: "Я покажу ваи кусочек кода", |
| 107 | + } |
| 108 | + } |
| 109 | + } |
| 110 | +} |
| 111 | +``` |
| 112 | +> Заметьте, __перевод__ содержит __не все поля__, которые присутствуют в стандартном языковом пакете. Поля, которых нет |
| 113 | +> переводе __будут взяты из стандартного пакета__. |
| 114 | +
|
| 115 | +Теперь, давайте передадим в компонент ```<DocsLayout/>``` параметр ___langs___: |
| 116 | +``` |
| 117 | +import React from 'react'; |
| 118 | +import ReactDOM from 'react-dom'; |
| 119 | +import * as serviceWorker from './serviceWorker'; |
| 120 | +
|
| 121 | +import DocsLayout from "@material-docs/core/components/DocsLayout"; |
| 122 | +import DocsPages from "@material-docs/core/components/DocsPages"; |
| 123 | +import DocsMenu from "@material-docs/core/components/DocsMenu"; |
| 124 | +import AutoDocsMenu from "@material-docs/core/components/AutoDocsMenu"; |
| 125 | +import PagesGroup from "@material-docs/core/components/PagesGroup"; |
| 126 | +import FirstPage from "./pages/FirstPage"; |
| 127 | +import SecondPage from "./pages/SecondPage"; |
| 128 | +import EN from "./locale/EN"; |
| 129 | +import RU from "./locale/RU"; |
| 130 | +
|
| 131 | +ReactDOM.render( |
| 132 | + <React.StrictMode> |
| 133 | + <DocsLayout |
| 134 | + name={"My documentation"} |
| 135 | + version={"1.0.0-alpha"} |
| 136 | + logo={"http://material-docs.com/static/media/logo.5a237c82.svg"} |
| 137 | + keywords={["my", "test", "documentation"]} |
| 138 | + description={"This is an example documentation for Material Docs framework."} |
| 139 | + author={"Danil Andreev"} |
| 140 | + defaultLang={EN} |
| 141 | +
|
| 142 | + langs={[EN, RU]} |
| 143 | + > |
| 144 | + <DocsMenu> |
| 145 | + <AutoDocsMenu /> |
| 146 | + </DocsMenu> |
| 147 | + <DocsPages> |
| 148 | + <PagesGroup name={"My Group"}> |
| 149 | + <FirstPage/> |
| 150 | + </PagesGroup> |
| 151 | + <SecondPage/> |
| 152 | + </DocsPages> |
| 153 | + </DocsLayout> |
| 154 | + </React.StrictMode>, |
| 155 | + document.getElementById('root') |
| 156 | +); |
| 157 | +
|
| 158 | +serviceWorker.unregister(); |
| 159 | +``` |
| 160 | +Теперь, кнопка выбора языка справа сверху интерфейса доступна и предлагает на выбор 2 языка. |
| 161 | +### Локализация интерфейса Material Docs |
| 162 | +Интерфейс MaterialDocs по умолчанию имеет английский язык. Для того, чтоб перевести его, необходимо добавить в следующую |
| 163 | +структуру в поле ___locale___ языкового пакета: |
| 164 | +```javascript |
| 165 | +export default { |
| 166 | + name: "ru-ru", |
| 167 | + label: "Русский", |
| 168 | + locale: { |
| 169 | + pages: { |
| 170 | + FirstPage: { |
| 171 | + header1: "Моё имя Данил Андреев", |
| 172 | + header3: "Я покажу ваи кусочек кода", |
| 173 | + } |
| 174 | + }, |
| 175 | + MaterialDocs: { |
| 176 | + navigationList: { |
| 177 | + content: "Содержание" |
| 178 | + }, |
| 179 | + tooltips: { |
| 180 | + selectLanguage: "Выбрать язык", |
| 181 | + switchTheme: "Переключить светлую/тёмную тему" |
| 182 | + }, |
| 183 | + copyright: "Создано с помощью MaterialDocs. Все права защищены.", |
| 184 | + SearchField: { |
| 185 | + "label": "Поиск..." |
| 186 | + }, |
| 187 | + notices: { |
| 188 | + codeCopied: "Кол скопирован в буфер обмена", |
| 189 | + codeNotCopied: "Не удалось скопировать код в буфер обмена" |
| 190 | + }, |
| 191 | + ExpansionCode: { |
| 192 | + copyToClipboard: "Скопировать код в буфер обмена", |
| 193 | + expand: "Развернуть/свернуть код", |
| 194 | + moreActions: "Больше действий" |
| 195 | + }, |
| 196 | + DemoWithCode: { |
| 197 | + copyToClipboard: "Скопировать код в буфер обмена", |
| 198 | + expand: "Развернуть/свернуть код", |
| 199 | + moreActions: "Больше действий" |
| 200 | + } |
| 201 | + } |
| 202 | + } |
| 203 | +} |
| 204 | +``` |
| 205 | +Теперь, интерфейс документации переведен. |
| 206 | +### Доступ к механизму локализации |
| 207 | +Вы можете получить доступ к механизму локализации с помощью хука ___useLang()___ или компонента высшего порядка ___withLang()___. |
| 208 | +Советуем пользоваться ими только в крайних случаях. |
| 209 | + |
| 210 | +## Исходники на GitHub |
| 211 | +Вы можете найти исходники этого примера на GitHub [здесь](&&GitHubLink) |
0 commit comments