@tilde-nlp/website-translator 8.2.0-beta.21 → 8.4.0-beta
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +59 -1
- package/dist/widget.js +1 -1
- package/dist/widget.js.LICENSE.txt +1 -1
- package/package.json +4 -3
- package/src/js/interfaces/IPluginOptions.ts +16 -0
package/README.md
CHANGED
|
@@ -8,11 +8,19 @@
|
|
|
8
8
|
|
|
9
9
|
# Website Translator
|
|
10
10
|
|
|
11
|
-
[](https://github.com/tilde-nlp/website-translator/actions/workflows/publish-beta.yml)
|
|
12
12
|
|
|
13
13
|
Quickly scale up from one language to a dozen!
|
|
14
14
|
No coding, manual translation, or duplicated webpages! Simply select the target languages and Website Translator will instantly translate the content. For quality control, you can review and edit translations with a visual editor.
|
|
15
15
|
|
|
16
|
+
Versions `8.x` are currently published under the npm `beta` dist-tag. See the [changelog](changelog.md) for release details.
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install @tilde-nlp/website-translator@beta
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
This installs the version currently assigned to npm's `beta` dist-tag. The tag is updated to the newest beta build after each successful beta publication. For reproducible installations, pin a full version such as `8.2.0-beta.42`.
|
|
23
|
+
|
|
16
24
|
# Usage
|
|
17
25
|
|
|
18
26
|
Include a reference to the Website Translator
|
|
@@ -70,6 +78,56 @@ Default language selector can be displayed as a dropdown or a list of buttons th
|
|
|
70
78
|
</html>
|
|
71
79
|
```
|
|
72
80
|
|
|
81
|
+
## Configure dynamic content discovery
|
|
82
|
+
|
|
83
|
+
`single-batch` and `word-count` modes wait for an inactivity window before completing dynamic content discovery. The window restarts whenever another discovery pass runs and defaults to 5000 ms.
|
|
84
|
+
|
|
85
|
+
Set `dynamicContentDiscoveryDelayMs` before initialization to accommodate the website's loading behaviour:
|
|
86
|
+
|
|
87
|
+
```HTML
|
|
88
|
+
<script>
|
|
89
|
+
WebsiteTranslator.Options.translation.mode = "single-batch";
|
|
90
|
+
WebsiteTranslator.Options.translation.dynamicContentDiscoveryDelayMs = 10000;
|
|
91
|
+
WebsiteTranslator.Initialize();
|
|
92
|
+
</script>
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
The same setting applies when `mode` is `"word-count"`. Set it to `0` to complete discovery immediately after the initial pass. Invalid or negative values use the 5000 ms default.
|
|
96
|
+
|
|
97
|
+
## Configure language URL persistence
|
|
98
|
+
|
|
99
|
+
By default, language changes preserve the existing behaviour: the widget stores the selected language in the `lang` query parameter and creates a browser history entry.
|
|
100
|
+
|
|
101
|
+
The `lang` parameter also gives each translated language a distinct URL that search engines can discover. The widget uses these URLs when localizing links and generating canonical and `hreflang` metadata. Use `"push"` or `"replace"` when translated variants should remain discoverable through `?lang=...` URLs.
|
|
102
|
+
|
|
103
|
+
SPAs can update the parameter without adding history entries, or leave routing entirely to the host application:
|
|
104
|
+
|
|
105
|
+
```HTML
|
|
106
|
+
<script>
|
|
107
|
+
// Use "replace" to keep ?lang=lv without creating a history entry.
|
|
108
|
+
WebsiteTranslator.Options.translation.languageUrlMode = "replace";
|
|
109
|
+
|
|
110
|
+
// Use "none" to prevent the widget from reading or writing ?lang and from adding it to links.
|
|
111
|
+
WebsiteTranslator.Options.translation.languageUrlMode = "none";
|
|
112
|
+
</script>
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Use `"none"` only when the host application owns language routing or translated pages should not be indexed separately. When using `"none"` for indexable translated pages, the host application must provide stable localized URLs and the corresponding canonical and `hreflang` metadata. Otherwise, search engines may not discover or correctly associate translated variants.
|
|
116
|
+
|
|
117
|
+
## SPA route translation lifecycle
|
|
118
|
+
|
|
119
|
+
The widget applies the same route lifecycle to `history.pushState`, `history.replaceState`, browser back/forward navigation, and hash-based navigation:
|
|
120
|
+
|
|
121
|
+
1. Invalidate queued, delayed, and in-flight work from the previous route.
|
|
122
|
+
2. Restore translated DOM that remains connected and remove detached translation state.
|
|
123
|
+
3. Reset route-specific discovery and processing state.
|
|
124
|
+
4. Prepare the current DOM for translation and restart dynamic content observation.
|
|
125
|
+
5. Translate content rendered immediately or discovered later by the SPA.
|
|
126
|
+
|
|
127
|
+
Route navigation uses a **restore and reprocess** policy. The widget does not preserve translated markup on elements that survive navigation because the host framework may reuse or mutate those elements as part of rendering the new route. Restoring source markup first gives the framework and the next discovery pass a consistent DOM.
|
|
128
|
+
|
|
129
|
+
Translation strings are cached by source content, item type, attribute, and target language. Route changes retain this cache, so unchanged content can be reapplied without another translation API request. Explicit language changes start a fresh translation execution and clear the cache. Source-language and third-party-language routes only invalidate and restore widget state; they do not start widget translation observation.
|
|
130
|
+
|
|
73
131
|
# Browser support
|
|
74
132
|
|
|
75
133
|
<!--
|