Tłumaczenie HTML i JavaScript za pomocą Weblate CDN

Starting with Weblate 4.2 it is possible to export JavaScript and HTML localization to a CDN using Lokalizacja JavaScript CDN add-on. To publish translation files without the JavaScript loader, use Translation files CDN.

Informacja

This feature is configured on Hosted Weblate. It requires additional configuration on your installation, see LOCALIZE_CDN_URL and LOCALIZE_CDN_PATH. See also Lokalizacja CDN.

Upon installation into your component the JavaScript localization add-on will push committed translations (see Leniwe zatwierdzenia) to the CDN and these can be used in your web pages to localize them.

Tworzenie komponentu

First, you need to create a monolingual component which will hold your strings, see Dodawanie projektów i komponentów tłumaczeniowych for generic instructions on that.

In case you have existing repository to start with (for example the one containing HTML files), create an empty JSON file in the repository for the source language (see Język źródłowy), for example locales/en.json. The content should be {} to indicate an empty object. Once you have that, the repository can be imported into Weblate and you can start with an add-on configuration.

Podpowiedź

In case you have existing translations, you can place them into the language JSON files and those will be used in Weblate.

For those who do not want to use existing repository (or do not have one), choose Start from scratch when creating component and choose JSON file as a file format (it is okay to choose any monolingual format at this point).

Konfigurowanie dodatku Weblate CDN

The Lokalizacja JavaScript CDN add-on provides few configuration options.

Próg tłumaczenia

Translations translated above this threshold will be included in the CDN.

Selektor CSS

Configures which strings from the HTML documents are translatable, see Wyodrębnianie ciągów dla Weblate CDN and Lokalizacja HTML przy użyciu Weblate CDN.

Nazwa pliku cookie języka

Name of cookie which contains user selected language. Used in the JavaScript snippet for Lokalizacja HTML przy użyciu Weblate CDN.

Wyodrębnianie ciągów z plików HTML

List of files in the repository or URLs where Weblate will look for translatable strings and offer them for a translation, see Wyodrębnianie ciągów dla Weblate CDN.

Wyodrębnianie ciągów dla Weblate CDN

The translation strings have to be present in Weblate. You can either manage these manually, use API to create them or list files or URLs using Extract strings from HTML files and Weblate will extract them automatically. The files have to present in the repository or contain remote URLs which will be download and parsed regularly by Weblate. Remote URLs are restricted by ALLOWED_ASSET_DOMAINS, including any redirect targets.

The default configuration for CSS selector extracts elements with CSS class l10n, for example it would extract two strings from following snippets:

<section class="content">
    <div class="row">
        <div class="wrap">
            <h1 class="section-title min-m l10n">Maintenance in progress</h1>
            <div class="page-desc">
                <p class="l10n">We're sorry, but this site is currently down for maintenance.</p>
            </div>
        </div>
    </div>
</section>

In case you don’t want to modify existing code, you can also use * as a selector to process all elements.

Informacja

Right now, only text of the elements is extracted. This add-on doesn’t support localization of element attributes or elements with children.

Lokalizacja HTML przy użyciu Weblate CDN

To localize an HTML document, you need to load the weblate.js script:

<script src="https://weblate-cdn.com/a5ba5dc29f39498aa734528a54b50d0a/weblate.js" async></script>

Upon loading, this will automatically find all matching translatable elements (based on CSS selector configuration) and replace their text with a translation.

The user language is detected from the configured cookie and falls back to user preferred languages configured in the browser.

The Language cookie name can be useful for integration with other applications (for example choose django_language when using Django).

Lokalizacja JavaScript

The individual translations are exposed as bilingual JSON files under the CDN. To fetch one you can use following code:

fetch(("https://weblate-cdn.com/a5ba5dc29f39498aa734528a54b50d0a/cs.json")
  .then(response => response.json())
  .then(data => console.log(data));

The actual localization logic needs to be implemented in this case.

Publishing translation files

The Translation files CDN add-on publishes translation files directly to the CDN. It does not generate a JavaScript loader or convert translations into bilingual JSON.

Single-file translations are named using the language code and original file extension, for example cs.json or de.po. Multi-file translations are served below the language code using paths relative to the translation directory. Monolingual components include the source language file, while bilingual components publish only target-language files. See Lokalizacja CDN for secure server setup.