Documentation

System Requirements

LingoSync needs only a few things to run.

• Sngine core – the addon only adds files and small additive patches; it never removes or rewrites existing Sngine logic.
• Default Sngine theme – the front-end template hooks ship wired up for the default theme.
• PHP version – whatever version your Sngine install already runs on.
• MySQL / MariaDB – two new tables (lingosync_cache, lingosync_usage) plus default rows in the existing system_options table.
• An OpenAI or DeepSeek account – you only need a key for whichever provider you pick as active; the other can stay empty.

Installation Guide

LingoSync is delivered as a handful of new files plus small, additive patches to files Sngine already ships. Nothing existing is removed or rewritten — go step by step and verify as you go.

mysql -u DBUSER -p DBNAME < sql/lingosync_install.sql

php -l includes/lingosync.php
php -l includes/ajax/lingosync/translate.php
ls -la includes/lingosync.php includes/ajax/lingosync/translate.php includes/assets/js/core/lingosync.js

Updating LingoSync

Updates ship the same way as the initial install — a set of files to re-upload, following the same order and the same verification habits. Treat every update like a fresh install of Step 3–5 above, not a blind overwrite.

Before you update

• Back up every file you're about to replace — not just the ones you think changed. If an update touches bootstrap.php, admin.php, or any template, back up all of them.
• Note which Sngine core version you're currently on. LingoSync's patches are additive against a specific Sngine release; if Sngine itself was updated first, re-check that the exact "find" text in each patch still matches your current files before overwriting.

Update order

1. Upload any brand-new files first (inert until referenced — safe to land ahead of time).
2. Upload bootstrap.php last among the "core" files, and only once every file it might require is already confirmed present with php -l. A bootstrap.php that requires a file which hasn't landed yet will fatal on every single page of your site, not just LingoSync's.
3. Upload admin.php / includes/ajax/admin/settings.php, then the AdminCP templates, then the front-end templates — testing navigation after each group.
4. Re-run sql/lingosync_install.sql if the update notes mention new tables or options — it's safe to run repeatedly.
5. Clear content/themes/default/templates_compiled/ and restart PHP-FPM after any template or core-file change.

Rolling back

If an update misbehaves, restore your pre-update backups of the files you just replaced (all of them, not just the ones you suspect) and clear templates_compiled/ again. Then re-apply the update one file group at a time, verifying after each, instead of all at once.

Core Features

LingoSync brings a full server-side AI translation layer to your Sngine community.

What You Can Do

• Choose your content types – Posts, Comments, Messages, Blogs, Profiles, Products, and general text, each with its own on/off switch.
• Pick a translation mode – Manual (click to translate), Automatic (translates instantly for every viewer), or both together.
• Cap your spend – set daily, weekly, monthly and yearly limits, or leave any window unlimited.
• Watch usage live – requests, cache hits, API calls and failures, broken down by day/week/month/year.
• Tune the model – model name, temperature, max output tokens and request timeout, per provider.

How It Works

From click (or page load, in Automatic mode) to translated text on screen, here's the exact path a request takes.

Request Flow

1. A visitor loads a page, or new content streams in (infinite scroll, a new chat message, a newly loaded comment).
2. In Automatic mode, LingoSync's script silently finds every eligible post/comment/message on the page and requests a translation for the viewer's language — no click needed. In Manual mode, nothing happens until the visitor clicks "Translate".
3. The request hits includes/ajax/lingosync/translate.php, which checks: is LingoSync enabled, is this content type enabled, does the current Translation Mode allow this specific request (manual clicks and automatic background scans are tagged separately, so a site set to "Automatic" only accepts automatic requests, and vice versa for "Manual"), is there text to translate, and is the target language supported.
4. LingoSync checks lingosync_cache for an identical (content type + original text + target language) combination. A cache hit returns instantly — no AI provider is called and no usage limit is spent.
5. On a cache miss, LingoSync checks your configured usage limits, then calls the active AI provider with a translation-only system prompt that preserves emojis, @mentions, #hashtags and links exactly as written.
6. The result is cached, usage is logged, and the translated text is returned to the browser.
7. The browser swaps the text in place — same element, same font, same layout — and the button becomes "View Original". A second click restores the original instantly, with no extra request.

Translation Modes

AI Engine & Limits

Every knob that controls translation cost and quality lives in AdminCP → Settings → LingoSync.

Content Types at a Glance

Defaults come straight from sql/lingosync_install.sql and can be changed anytime under Translation Features — only enabled content types ever consume AI credits.

Changelog

All notable changes to LingoSync are documented here.

Frequently Asked Questions

Quick answers to the most common questions about LingoSync.