# Оболонка Weblate

Інтерфейс наразі побудовано з використанням Bootstrap, jQuery та кількох сторонніх бібліотек.

## Підтримувані браузери

У Weblate передбачено підтримку найсвіжіших стабільних випусків усіх основних браузерів та програмних платформ.

Підтримки альтернативних браузерів, які використовують найсвіжішу версію WebKit, Blink або Gecko безпосередньо або за допомогою програмного інтерфейсу перегляду даних інтернету платформи, явним чином не передбачено. Втім, Weblate має (у більшості випадків) показувати дані і працювати належним чином і у цих браузерах.

Застарілі браузери можуть працювати, але працездатність деяких можливостей у них може бути обмежено.

## Accessibility

Weblate targets WCAG 2.2 Level AA for new and changed user-facing
functionality where practical. Use semantic HTML and Bootstrap components
before adding custom interaction code.

When changing the frontend:

- Make all interactive controls reachable and usable with a keyboard.
- Keep focus order logical and preserve visible focus styling.
- Prefer native buttons, links, inputs, selects, and tables over custom widgets.
- Associate every form control with a label, help text, and validation errors
  where applicable.
- Do not use color, icon shape, or position as the only way to convey state.
- Announce dynamic status changes that are not otherwise visible to assistive
  technology.
- Respect reduced-motion preferences for animation or scrolling behavior.
- Test changed workflows with keyboard-only navigation and, when practical, a
  screen reader spot check.

## User interface conventions

### Documentation links

Use the information icon for contextual links to the Weblate documentation
instead of a textual Documentation button. In Django templates,
use the `documentation_icon` template tag so that the link has consistent
styling, labeling, and external-link behavior. Documentation icons are
interactive links and have to remain keyboard-focusable. Keep textual
documentation links when they are part of explanatory prose rather than a
contextual action.

## Керування залежностями

Встановлення бібліотек сторонніх розробників і керування ними в «клієнті» проекту Django може бути дещо складним. У цьому розділі наведено покрокові інструкції щодо встановлення та керування сторонніми бібліотеками, які використовуються на «клієнтській стороні» Weblate за допомогою «Webpack».

### Передумови

Перш ніж приступити до встановлення, переконайтеся, що у вас є наступні передумови:

- A supported `Node.js` release.
- У вашій системі встановлено менеджер пакетів `yarn`.
- Запустити `cd client`.
- Run `yarn install --check-files`.

### Установлення

Щоб інсталювати бібліотеку, спочатку виконайте таку команду:

```bash
yarn add <lib-name>
```

### Імпортування бібліотеки

Існує два способи імпортувати бібліотеку:

1. Якщо це бібліотека всього проєкту (використовується/потрібна на всіх/більшості сторінок):
   : - Імпортуйте бібліотеку в `src/main.js`.
     - І оголосити його в глобальній області видимості (якщо потрібно).
2. Якщо це сторінка-специфічна бібліотека (бібліотека використовується в конкретній сторінці або шаблоні):
   : - Створіть новий файл з назвою `src/<lib-name>.js`.
     - Імпортуйте бібліотеку у ньому. Далі вставте його до об’єкта `window` для загального доступу.
     - Додайте запис до `webpack.config.js`: `<lib-name>: «src/<lib-name>.js»`.
     - Додайте назву бібліотеки до масиву `excludePrefixes` у `mainLicenseTransform` у `webpack.config.js`.
     - Додайте назву файла ліцензування до `additionalFiles` у `LicensePlugin` у масиві `plugins` у `webpack.config.js`.
     - Створіть функцію `<lib-name>LicenseTransform` для файлу ліцензії, представленого в попередніх кроках, та використовуйте її.

   Примітка: Замініть `<lib-name>` на справжню назву сторонньої бібліотеки.

### Збирання бібліотеки

Зберіть бібліотеки, що використовуються проєктом, запустивши таку команду:

```bash
yarn build
```

### Включення бібліотеки

Тепер бібліотека зібрана і готова до використання. Щоб включити її, виконайте такі кроки:

1. Якщо бібліотеку було імпортовано в `rc/main.js`, подальших дій не потрібно (оскільки вона вже включена в `base.html`).
2. Якщо бібліотека була імпортована в окремому файлі `src/<lib-name>.js`, в `weblate/templates` використовуйте теги include для посилання на зібраний статичний файл JavaScript:

```django
{% load static %}
<script src="{% static 'js/vendor/<lib-name>.js' %}"></script>
```

## Стиль програмного коду

Weblate relies on [Biome](https://biomejs.dev/) for formatting and linting the JavaScript and CSS
code. Django templates are formatted and linted separately by **djade**
and **djlint**.

## Локалізація

Якщо вам потрібен видимий користувачеві текст у коді інтерфейсу, він має бути локалізованим. У більшості випадків все, що вам потрібно, це обернути текст у функцію `gettext`, але є більш доступний складні функції :

```javascript
document.write(gettext("this is to be translated"));

var object_count = 1 // or 0, or 2, or 3, ...
s = ngettext("literal for the singular case",
        "literal for the plural case", object_count);

fmts = ngettext("There is %s object. Remaining: %s",
        "There are %s objects. Remaining: %s", 11);
s = interpolate(fmts, [11, 20]);
// s is "There are 11 objects. Remaining: 20"
```

#### SEE ALSO
[Translation topic in the Django documentation](https://docs.djangoproject.com/en/stable/topics/i18n/translation/)

## Піктограми

Weblate наразі використовує [Material Design Icons](https://pictogrammers.com/library/mdi/), якщо ви шукаєте новий символ, перевірте це.

Крім того, можна скористатися `scripts/optimize-svg` для зменшення розміру SVG, оскільки більшість піктограм вбудовуються до HTML для уможливлення застосування стилю до контурів.