Read Me First — Multi-Language Customer Support

Welcome. This document is for anyone meeting this project for the first time. It explains, in plain language, what this software is, who it is for, and how to get started with it. You do not need any technical background to read it.

---

1. Who this is for

This project serves three kinds of people inside a company that offers customer support:

• Support agents — the people who answer customer questions every day. They read and reply to customer conversations, including ones written in languages they do not speak.
• Support operations managers and administrators — the people who set the system up: connecting the company's existing support tool, maintaining the company's vocabulary list, and supervising translations that need a human eye before they reach a customer.
• Customer experience (CX) leaders — the people responsible for whether support is actually working. They use the reports to see, language by language, how quickly customers are helped, how satisfied they are, and what the translation service costs.

A typical adopting organization is a business with customers in many countries but a support team that works in one or two languages.

2. What it does

In a few plain sentences:

When a customer writes to your company in their own language — say Japanese — the software detects the language automatically, translates the message into your agent's working language, and shows it to the agent alongside the original text. The agent replies in their own language, and the customer receives the reply translated back into Japanese. Neither side installs anything new, and your team keeps working in the support tool it already uses.

Around that core loop, the software also:

• Protects your brand vocabulary, so product names and approved terminology survive translation intact, in every language.
• Scores the quality of every translation, flags uncertain incoming messages, and holds uncertain outgoing replies for a human to approve before the customer sees them.
• Learns from agents' corrections, so the same mistranslation does not happen twice.
• Translates your help-center articles into every language you support and warns you when a translation has gone out of date.
• Reports, per language, on customer satisfaction, resolution times, volumes, translation quality trends, and cost — and alerts you when quality for a language starts to slip, before customers notice.

It works across more than fifty languages, over email, chat, and web-form (ticket) channels.

3. The domain

This project lives in the world of customer support operations.

Most growing companies use a helpdesk — a system such as Zendesk, Salesforce Service Cloud, or Freshdesk — where customer questions arrive as tickets, chats, or emails, and agents answer them. This works well until the customer base becomes international. A company selling in forty countries receives questions in dozens of languages, but hiring fluent support agents for every language is expensive and often impossible for smaller languages.

The common answers today each have a drawback:

• Some helpdesks offer built-in translation, but only if you adopt (or stay locked into) that vendor's whole product family.
• Standalone translation services exist, but general-purpose machine translation regularly mangles product names, technical terms, and brand voice — the exact words that matter most in a support reply.
• Almost nothing on the market tells you, in advance, that translation quality for a particular language is quietly getting worse.

This project is built for that gap: it is a translation layer designed specifically for customer support, sitting between the helpdesk a company already has and the customers it serves, in their own languages.

4. Where it fits

The software is middleware — it does not replace anything you use; it connects things you already have.

• On one side, your helpdesk. Ready-made connectors exist for Zendesk, Salesforce, and Freshdesk. Connecting one is an authorization step done by an administrator — the kind where you sign in to the helpdesk and grant access — and typically takes an engineer less than an hour. Agents keep working in the helpdesk exactly as before. For other systems, the platform offers a programming interface and a webhook mechanism so custom tools can be connected as well.
• On the other side, professional translation services. The actual translation is performed by well-known machine-translation providers — Google, DeepL, Microsoft Azure, and Amazon. Your organization chooses which providers to use. If one provider is unavailable or performs poorly for a language pair, the platform switches to another automatically, with nothing visible to the customer. Your terminology rules are applied identically no matter which provider does the translation.
• Your company's sign-in system. There are no separate passwords for this product. People sign in with the organization's existing single sign-on (handled through the hosting platform's identity service), and each person is recognized by that identity.
• AI assistants. Translation, language detection, glossary lookup, and conversation routing are also exposed as tools that authorized AI assistants can call directly, so automated agents can use the same translation pipeline with the same terminology rules.

Customers and end users: your customers never interact with this software directly and do not need an account. They simply write to your support address or chat widget as usual and receive replies in their language. The people with accounts are your agents, reviewers, and administrators.

Privacy posture: each customer's data is kept strictly separate from every other customer's. Conversation content is processed only through the translation providers your organization selected, and it is never used to train shared or public models. If a customer asks for their data to be erased (a GDPR-style request), the platform can remove that person's data completely without touching anyone else's.

5. First run

The very first thing to do with a freshly started system is sign in to the administrator console and open the dashboard.

Signing in uses your organization's single sign-on: you open the console address, you are redirected to your company's sign-in page, you sign in as usual, and you land back in the console. The first person set up (by whoever initializes the environment) becomes the owner of the workspace.

The dashboard is the operational home screen. It shows, at a glance:

• how much conversation volume is flowing, broken down by language;
• the average translation-confidence trend for each language pair;
• any open quality alerts.

If you are exploring a preview or evaluation copy, it comes pre-loaded with sample data (see "Sample data and starting fresh" below), so the dashboard, glossary, reports, and alerts already have realistic content to look at. A good first hour is simply to click through the console: Dashboard, Glossaries, Pending terms, Integrations, Review queue, Knowledge base, Analytics, and Alerts. Each is described under "Day to day" below.

6. Setting up

Getting from a fresh system to a fully working environment happens in this order. The first step is a one-time job for whoever operates the platform; the rest are ordinary administrator tasks done in the console.

1. Initialize the environment (one time, operator task). Before first use, a stage or production environment must be initialized: this wipes any leftover data, creates your organization's workspace, and registers the first administrator. The procedure is deliberately guarded — it prints exactly what will be deleted and created and requires explicit confirmation — because it erases existing data. The full, step-by-step procedure is in the companion document production-initialization.md (see the document map below). A preview or local evaluation copy skips all of this and arrives pre-loaded with sample data instead.
2. Connect your helpdesk. In the Integrations area of the console, add a connection to your helpdesk (Zendesk, Salesforce, or Freshdesk). You authorize access by signing in to the helpdesk through its normal approval flow; the platform never stores your raw password or keys, only a protected reference to them. For each connection you choose which channels (chat, email, web forms) should be translated. From then on, events from the helpdesk arrive over a verified, tamper-proof channel — anything that fails verification is rejected and recorded.
3. Choose your languages and translation providers. Enable the languages you want to serve (the platform's language registry covers more than sixty languages, including regional variants such as Castilian versus Latin American Spanish), and configure which translation provider accounts to use. You can prefer a specific provider per language pair; failover to another provider is automatic.
4. Set up your brand glossary. In the Glossaries area, register the words that must survive translation: product names marked "do not translate," and approved term mappings (for example, your approved Spanish equivalent for "refund"). Every translation the platform produces honors this list, on every provider.
5. Set your quality threshold and reviewers. Decide the confidence level below which outgoing replies are held for human review, and make sure the right people hold reviewer-level roles (see "User roles" below). Incoming messages are never held back — agents always see the customer immediately, with uncertain translations simply flagged.
6. Optionally, load your help center. Import or create knowledge-base articles and request translations into your supported languages. The platform tracks each language version's status, and translation jobs can be exchanged with external translation tools through XLIFF, the standard industry interchange format.

There is no customer-side setup: your customers change nothing.

7. Day to day

Once connected, routine use looks like this.

For a support agent (in the helpdesk they already use):

• A customer message arrives in any supported language. The agent sees it in their own working language, with the original text always visible alongside, plus a note of which language was detected.
• If the incoming translation was uncertain, it is still shown immediately — just marked with a low-confidence flag, so the agent knows to read it with care.
• The agent writes the reply in their own language and sends it as usual. The customer receives it in theirs.
• If a customer switches language mid-conversation, each new message is detected and translated on its own.
• If the agent spots a mistranslated term, they correct it. That correction is remembered and, once the same correction has been seen a few times, the platform proposes it as a permanent glossary improvement (nothing enters the glossary silently — a human approves each suggestion).
• If a conversation needs a human specialist, it can be escalated; the receiving agent gets the full history with both the original and translated text preserved.

For a reviewer or operations manager (in the console):

• Review queue. Outgoing replies whose translation confidence fell below your threshold wait here instead of reaching the customer. The reviewer always sees the bilingual truth — the agent's original words and the machine translation side by side — and can release the message as-is or edit it first and then release it.
• Pending learned terms. Corrections that agents keep making surface here as suggested glossary entries. Each is approved or rejected with one click, and every decision is recorded in the audit log.
• Glossaries. Maintain the do-not-translate list and approved term mappings as products and terminology evolve.
• Knowledge base. Publish articles and track each language version's status — machine-translated, human-reviewed, or outdated. When a source article changes, the affected translations are flagged outdated and an alert is raised, so customers are not left reading stale content. One click marks a machine-translated version as reviewed.

For a CX leader (in the console):

• Analytics. See, per language: conversation volumes, resolutions, first-contact resolution, customer satisfaction, and response and resolution times — alongside the translation-confidence trend for each language pair. Because the platform records the cost of every translation, spend per language pair is transparent, so you can compare the real cost of machine translation against the cost of hiring multilingual staff.
• Quality alerts. The platform watches quality trends per language continuously. When a sustained decline crosses the threshold, it raises an alert identifying the language pair — typically days before the decline would show up in satisfaction scores. You acknowledge alerts here, and that acknowledgement is recorded like every other security-relevant action.

If something goes wrong in the translation services themselves: if every configured provider is unavailable at once, the platform does not block support. It delivers the original text, clearly flagged as untranslated, and completes the pending translation automatically once service recovers.

8. Ongoing care

The platform is designed to run quietly, but a few recurring and long-term responsibilities are worth scheduling.

• Review the quality alerts regularly. Alerts flag languages whose translation quality is drifting downward. Acknowledging and acting on them early is the cheapest way to protect customer satisfaction.
• Check the review queue daily. Held outgoing replies wait there until a human releases them; an unwatched queue means customers waiting.
• Approve pending learned terms periodically. This is how the glossary improves itself — a few minutes of review keeps terminology getting better without manual curation.
• Watch the analytics monthly. Per-language satisfaction, volumes, and cost reports support staffing and budgeting decisions; per-language-pair costs make spend forecastable.
• Keep help-center translations current. When outdated-translation flags appear after source edits, re-translate and re-review the affected languages.
• Data retention is automatic. Conversation content (messages and their translations) is deleted once it passes your retention window — twelve months rolling by default, adjustable per organization. A nightly cleanup handles this; no manual purging is needed. Erasure requests from individual customers are honored at any time, regardless of the window.
• Audit trail. Security-relevant events — sign-ins, integration changes, glossary approvals, rejected helpdesk events, erasure requests — are recorded permanently in an audit log. No secret values are ever written to it.

---

Glossary of terms

• Helpdesk — the system a company uses to receive and answer customer questions (for example Zendesk, Salesforce Service Cloud, or Freshdesk). Also called a ticketing system or support desk.
• Agent — a support-team member who answers customers.
• Tenant / workspace / organization — one company using the platform. Each organization's data is completely separate from every other's.
• Translation provider — an external machine-translation service (Google, DeepL, Microsoft Azure, or Amazon) that performs the actual translation.
• Language pair — a direction of translation, such as English to Spanish.
• Confidence score — the platform's estimate of how trustworthy a single translation is. Low scores trigger flags (incoming) or holds (outgoing).
• Review queue — the waiting area for outgoing replies whose translation confidence was too low to send automatically.
• Glossary — your organization's protected vocabulary: product names that must never be translated, and approved equivalents for terms that must always be translated the same way.
• Learned term — a glossary improvement the platform proposes after noticing agents repeatedly making the same correction. It takes effect only after a human approves it.
• Translation memory — the platform's store of previously approved translations. When a very similar text appears again, the approved wording is reused instead of re-translated, keeping wording consistent.
• Knowledge base (KB) — your help-center articles. The platform translates each article into your supported languages and tracks the status of every version.
• XLIFF — the standard industry file format for exchanging translation work with external translation tools and vendors.
• CSAT — customer satisfaction score, collected after conversations.
• First-contact resolution (FCR) — the share of conversations resolved in a single exchange, without follow-ups.
• Single sign-on (SSO) — signing in with your organization's existing identity rather than a separate password. This product has no passwords of its own.
• MCP server — a built-in doorway that lets authorized AI assistants use the platform's translation, detection, glossary, and routing capabilities as tools.
• Data-subject (erasure) request — a person's request, under privacy law such as GDPR, to have their personal data deleted.

The documents in this folder

This folder (user-docs/) holds documentation written for users and operators rather than developers:

• READ-ME-FIRST.md — this document. Orientation for a first-time reader: what the product is, who it is for, and how to start.
• production-initialization.md — the operator's procedure for preparing a stage or production environment for first use (or re-initializing it): creating the first workspace and administrator, with all the safety checks explained. Read it before initializing any real environment; you do not need it for a local preview.
• store-thumbnail.png — the product's thumbnail image for marketplace or catalog listings. Reference artwork, not documentation.

User roles

People are signed in through your organization's single sign-on and each person belongs to your workspace with one of four roles:

• Agent — works conversations. Reads translations, replies, corrects terms, escalates to humans.
• Supervisor (reviewer) — everything an agent can do, plus release held outgoing translations from the review queue (approve, or edit and release).
• Admin — supervisor abilities plus configuration: integrations, glossaries, knowledge-base management, and workspace settings.
• Owner — full control; the role held by the first administrator created at initialization.

By default, releasing a held outgoing translation is restricted to supervisor, admin, and owner. An organization can widen or narrow that permission in its settings. Automated (API) clients need a corresponding release permission to perform the same action.

Sample data and starting fresh

What ships in the preview: evaluation copies of the platform come pre-loaded with a demo workspace ("Demo Tenant") containing:

• a demo administrator sign-in for exploring the console;
• the full language registry (more than sixty languages with regional variants);
• a sample brand glossary ("Demo Brand") with a do-not-translate product name and approved term mappings;
• about two weeks of example analytics — daily conversation metrics, translation-quality trends, and provider performance across several languages — so the dashboard and reports have realistic content;
• one example quality alert, so the alerts view is populated.

The console tour screenshots (in the project's documentation) show what a fully exercised workspace looks like in action — including held items in the review queue, pending learned terms, connected helpdesks, and knowledge-base translations in several states.

Starting fresh: the sample data is strictly separate from real use. Preparing a stage or production environment means running the clean initialization described in production-initialization.md, which erases everything (including demo data) and creates only your workspace and your first administrator. Two warnings worth repeating from that document: the initialization is destructive and guarded accordingly, and the demo data must never be loaded into a real production workspace — its demo administrator is bound to an unauthenticated test identity intended only for local evaluation.

FAQ and common gotchas

• Do my agents have to learn a new tool? No. Agents keep working in the helpdesk they already use; translation happens inside that flow. The console is for reviewers, managers, and administrators.
• Do customers need accounts or software? No. They write and receive replies exactly as before, in their own language.
• A customer's message arrived flagged "low confidence" — was it blocked? No. Incoming messages are never held back. The flag simply tells the agent to read with care. Only uncertain outgoing replies are held, and those wait in the review queue for a human.
• An agent's reply didn't reach the customer. Where is it? Almost certainly in the review queue: its translation scored below your confidence threshold. A supervisor, admin, or owner can release it there.
• A product name was translated anyway. Check the glossary: the name must be registered as "do not translate." Once it is, every provider honors it. If an agent keeps fixing the same term, that correction will surface as a pending learned term for approval.
• The customer switched languages mid-conversation. Expected and handled: each message's language is detected independently.
• A helpdesk event was rejected. Incoming events from the helpdesk are verified for authenticity and protected against replays. A rejection means verification failed; it is recorded, and the event does not enter the translation pipeline.
• The translation services are down. Are we stuck? No. The platform fails over between providers automatically; if all of them are unavailable, it delivers the original text flagged as untranslated and completes the translation when service returns.
• Does the platform translate phone calls? Not in this version. Email, chat, and ticket (web form) channels are supported; voice is a planned future addition.
• How long is conversation data kept? Twelve months rolling by default, adjustable per organization; cleanup is automatic. Individual erasure requests are honored at any time.
• Is our conversation data used to train anyone's models? No. Content is processed only through the translation providers your organization selected, and it is never used to train public or shared models.

Where to get help

This project is part of the WBSP (World's Biggest Software Project) initiative. For questions, discussion, and community support, visit the wbsp.ai community (https://wbsp.ai). Contributions, feedback, and domain expertise are welcome — the project is open source.