Differences

This shows you the differences between two versions of the page.

--- google_translate [2026/10/20 17:27] – Synchronize English documentation with canonical Russian pages; reviewed locally 2026-10-20 user
+++ google_translate [2026/11/03 20:55] (current) – Document translation settings, Custom adapter and standalone API example admin
@@ Line 1: / Line 1: @@
-====== Google translate ======
+====== Text translation ======
-The script includes built-in Google Translate API integration for automatic text translation. Note that this is a paid service (Google charges for usage). To use it, visit https://developers.google.com/translate/v2/faq and obtain your **Server API Key** (not the Browser key).
+If you run several language versions of your site, SCJ can automatically translate gallery and category text through third-party services (Google or DeepL) or your own service.
-===== Translation of Existing Database =====
+===== Configuration =====
-To translate your existing gallery database, connect to your server via SSH and run:
+Open **Rotation → Settings → Translators**.
-  php rotation.php action=translate
+  - Select an adapter: **Google**, **DeepL** or **Custom**.
+  - Enter the service's key in **API key**.
+  - Select the source language. **Auto** asks the service to detect it.
-(from the scj/bin directory)
+The defaults are Custom and English (en). Custom is an example for building your own translation service.
-If you run this on a slave site, the results are saved there as well. This is useful if you have a master with English descriptions and want to add a German-language slave.
+Google and DeepL use your accounts with those providers. Sign up with the provider to obtain your free API key.
-The script will prompt you to:
+===== Translating an individual field =====
-. Select which field to translate (if you have both description and alt text, you'll need to run this twice)
+Text fields have a translation icon beside them. SCJ translates **the current text in that same field**, including unsaved edits, into the selected site's language.
-. Choose where to save the translated text
-. Enter your Google Translate API key
-Then you'll choose a translation mode:
+The result appears in the same field. Use the form's normal Save button to save it.
-- **stops:** The script pauses after each phrase so you can manually review and correct the translation before saving to the database
+===== Existing and new galleries =====
-- **log:** Translates without pausing, but shows the output for review
-- **fast:** Translates as quickly as possible with no pauses or output
-For best results, use UTF-8 encoding when connecting to the shell.
+For existing galleries, select **Fields to translate** under Translators and save the settings. Then open **Rotation → Settings → Multilingual → Existing languages** and use **Translate** for the required language.
-===== Translation of New Entries =====
+Bulk translation reads the source site's text and overwrites the selected fields on the language site.
-To automatically translate new galleries as they're imported, configure translation rules in [[Import Replacements]]. Here's how:
+For categories, use **AutoTranslate All** on the categories page. After confirmation, it overwrites the translatable fields of all categories for the language sites.
+For new galleries, enable **Rotation → Settings → Grabber Settings → Translate to Existing lngs**. It is off by default. After a successful initial grab, SCJ translates missing language fields according to Fields to translate. Explicitly supplied nonempty translations are preserved; a regrab does not trigger this translation.
+===== Building your own service (Custom) =====
+The adapter is ''includes/libs/translators/Custom.php''. Its default endpoint is the server example:
 <code>
+examples/translation-api/index.php
+</code>
-If this field = URL
+The URL is built from the configured site URL and SCJ folder. For an installation under /scj, it looks like this:
-Contains this value = http (matching all galleries)
-Then Search For - * (the entire field)
-in This Field - Custom Vars 1 (we'll store translation here)
-And Replace it With - external::http://YOURDOMAIN/scj/bin/rotation.php?action=translate_text&text={DESCRIPTION}&source_lng=en&target_lng=de&api_key=YOUR_API_KEY
+<code>
+https://example.com/scj/examples/translation-api/index.php
 </code>
-When a gallery is imported, the script makes a request to the URL above. The Custom Vars 1 field receives the translation result returned by the URL. For example, Custom Vars 1 will contain the German translation of the description.
+The request flows from the admin button to the SCJ server, through Custom to the HTTP API, and back into the field.
-Key features of this approach:
+**The example does not perform real translation.** It returns the original text with a language prefix, such as ''[de] Hello world''. Use it to check connectivity and the protocol first.
-- **external::** prefix tells the script to fetch the result from an external URL (not just replace text)
+Save ''demo-key'' in the Custom settings and click a translation icon beside a populated field. If you previously cleared the key, enter it again and Save.
-- **{DESCRIPTION}** is replaced with the actual gallery description
-- **source_lng=en&target_lng=de** specifies the source and target languages
-- **api_key** should be your Google API key
-You can save the translation to a slave field. For example, if you have an English master site and a German slave, set up this rule once on the master and save results to the slave's description field.
+===== API protocol and a curl check =====
-The built-in translation has limitations and its results may not always suit your needs. Import Replacements lets you use your own translation script, for example ''external::http://YOURDOMAIN/my_script.php?text={DESCRIPTION}'', to improve translations, cache repeated phrases, or otherwise process the text.
+For example, Custom sends a POST request with JSON and an X-Api-Key header. Replace the domain and folder with those of your installation:
+<code bash>
+curl 'https://example.com/scj/examples/translation-api/index.php' \
+  -H 'Content-Type: application/json' \
+  -H 'X-Api-Key: demo-key' \
+  --data '{"text":"Hello world","source":"en","target":"de"}'
+</code>
+Example response:
+<code json>
+{"text":"[de] Hello world"}
+</code>
-In the example configuration above, the API key is stored in the database. If you give someone a copy of that database, they can read the key. You can instead keep the key in your own translation script, including on a separate server.
+  * ''text'': source text in UTF-8; spaces, plus signs, percent escapes and the string “0” are preserved.
+  * ''source'': a source language such as en, or auto.
+  * ''target'': the target language, such as de; auto is not allowed here.
-This flexibility lets you customize how imported text is processed.
+A successful response must have HTTP status 200 and a string field named text. API errors use a different HTTP status and a JSON error field. Custom does not substitute the original text for a failed translation.