Multi-Language & Global Translation Guide

Visperity provides an enterprise two-tier multi-language architecture allowing international merchants to serve global customers seamlessly across multiple languages:

  1. Tier 1: Scoped Builder UI Localization: Translates widget buttons, input placeholders, price prefixes, headings, and validation messages for each search widget without touching dataset URLs.
  2. Tier 2: Knowledge Base & Vector Catalog Translation: Translates catalog articles, products, titles, excerpts, prices, and generates localized 1536-dimensional vector embeddings.
┌────────────────────────────────────────────────────────────────────────┐
│                        VISPERITY TRANSLATION ARCHITECTURE              │
├───────────────────────────────────┬────────────────────────────────────┤
│   TIER 1: BUILDER UI LOCALIZATION │ TIER 2: KNOWLEDGE BASE TRANSLATION │
├───────────────────────────────────┼────────────────────────────────────┤
│ • Virtual Assistant Translations  │ • Centralized in Datasets Section  │
│ • Live Search Translations        │ • Language Enable Checkboxes       │
│ • Embedded Search Translations    │ • Live Counters: X / Y Translated  │
│ • Placeholders, Buttons, Headers  │ • Incremental Delta Queueing       │
│ • Price Prefix (e.g. "Precio: ")  │ • Expandable Child Subsets         │
│ • 1-Click AI Auto-Translate       │ • Retranslate & Re-Embed Records   │
└───────────────────────────────────┴────────────────────────────────────┘

1. Strict Language Gating & Search Matching

To ensure 100% accurate, relevant, and culturally native responses:

  • Target Language Matching: When a customer conducts a search on a localized storefront (e.g. Spanish es), Visperity only searches and ranks records indexed in Spanish.
  • Default Language Gating: When a customer searches without a specific language code or in English, Visperity searches English catalog records.
  • Zero Cross-Language Contamination: English products or descriptions will never pollute Spanish, French, or German search results.

2. Builder UI Translations (Per-Widget Scoping)

Every builder (AI Virtual Assistant, Live Search, and Embedded Results) contains its own scoped 🌐 UI Translations subtab.

How to Localize a Widget Interface:

  1. Open the builder for the widget you want to translate (Assistant, Live Search, or Embedded Search).
  2. Click the 🌐 UI Translations subtab.
  3. Select your target language pill (e.g. 🇪🇸 Spanish, 🇫🇷 French, 🇩🇪 German).
  4. Click the ✨ AI Auto-Translate button for instant AI localization, or type manual translations into the input fields.
  5. Click 💾 Save Translations.

Localized Builder Fields:

  • AI Virtual Assistant: Welcome Greeting, Chat Header Title, Search Placeholder, Submit Label, Floating Opener Label, "I'm Finished" Close Label, "I Need More Help" Label, Price Prefix.
  • Live Search: Search Input Placeholder, Price Label (Price: vs Precio: ), Min Characters Error Message, No Results Found Message.
  • Embedded Search: Search Form Placeholder, Submit Button Label, Results Header Title, "More Info" Link Label, Price Prefix, "Show More Results" Pagination Label, Min Characters Error, No Results Message.

3. Multi-Language Knowledge Base Translation Manager

All dataset content translation is managed centrally in Datasets (section=datasets) directly above the indexed records table.

Features of the Knowledge Translation Manager:

  • Language Enable Checkboxes: Toggle individual languages on or off. Translations are only generated for enabled languages.
  • Live Progress Counter: Displays real-time progress for each language (e.g. 142 / 150 (95%) Translated vs base English source records).
  • Sync Status Badges:
    • ✓ Up to Date: All English source records have corresponding translated vector embeddings.
    • ⚠️ X Untranslated: New English records were added or imported and need translation.
    • ⚡ Z in Queue: Translations currently pending in the background Ingestion Queue.
  • Incremental "Translate Untranslated" Action:
    • Clicking Translate Untranslated detects newly added English articles and queues only the missing delta into the Ingestion Queue.
    • Generates an instant toast notification with the count of queued records.

4. Expandable Child Translation Hierarchy & Record Actions

In the Indexed Content table, records are organized in a clean parent-child hierarchy:

▼ 🇺🇸 English Primary Record (e.g. "Acme Ergonomic Chair" - $299.00)
    ├─ 🌐 🇪🇸 Spanish Child Translation ("Silla Ergonómica Acme" - $299.00) [Edit] [Retranslate] [Delete]
    └─ 🌐 🇫🇷 French Child Translation ("Chaise Ergonomique Acme" - $299.00) [Edit] [Retranslate] [Delete]

Hierarchy & Actions:

  1. Expand / Collapse Toggle: Click ▶ 🌐 X Translations on any English record to reveal its child translated records directly underneath.
  2. ✏️ Edit Translation: Open the Edit modal to manually adjust translated title, content, excerpt, price, or thumbnail image, and immediately re-vectorize the embedding.
  3. ⚡ Retranslate & Re-Embed: Instantly re-run AI translation from the parent English record and generate a new 1536-dimensional vector embedding for that specific language.
  4. 🗑️ Delete Translation: Delete an individual language translation without affecting the primary English record. (Deleting a primary English record automatically cleans up all associated child translations).
  5. Language Filter: Use the top-level Language Filter dropdown to view all languages in hierarchical mode or filter directly to a specific language.

5. Pricing, Thumbnail Images & Category Tag Translations

  • Localized Pricing: Product prices (e.g. $49.99, 49,99 €, £39.99) are preserved during translation and can be edited per language variant.
  • Thumbnail Images: Featured thumbnail images are automatically linked to child translations, allowing visual search results across all supported languages.
  • Category Tag Translations: Category labels (e.g. PRODUCTS, FAQ, SUPPORT) assigned to primary English records are included in the translation payload and automatically localized into target languages during batch translation. Admins can also manually update translated category tags inline in the records table.
← 5. Embedded Search Builder 📚 All Documentation Guides 7. Troubleshooting & FAQ →