Wheels Internationalization(i18n) Google Translator

Runtime HTML & text translation plugin for Wheels 3.x using Google Translate API

Translate entire pages on-the-fly without JSON files or database tables.

---

Features

• Full page HTML translation (markup-safe)
• Plain text translation
• Session-based language switching
• Optional in-memory caching
• Zero schema / zero migration
• Works with Wheels + BoxLang

Use case: Perfect when you need instant multilingual pages without managing translation files.

---

Installation

wheels plugin install wheels-googleTranslator

---

Configuration

Add the following settings to config/settings.cfm:

set(gt_defaultLanguage="en");
set(gt_availableLanguages="en,es,fr");
set(gt_apiKey="YOUR_GOOGLE_API_KEY");
set(gt_cacheEnabled=false); // set true in production

To obtain a Google Cloud Translation API key, follow the official setup guide: https://cloud.google.com/translate/docs/setup

Note: You will need a Google Cloud project with billing enabled. New users get free credits to start.

Configuration Options

Setting	Default	Description
gt_defaultLanguage	en	Default / fallback language
gt_availableLanguages	en	Comma-separated allowed languages
gt_apiKey	empty	Google Translate API key
gt_cacheEnabled	false	Cache translated output in memory

---

Plugin Functions

• #whlsGt("text", "language", "format")# → Translate Single Text
• #whlsGtTranslate("text", "language")# → Translate Full Page
• #whlsCurrentLanguage()# → Get current language
• #whlsChangeLanguage("es")# → Switch language
• #whlsAvailableLanguages()# → Array of supported languages

---

Usage: Key Functions

Translate Single Text - whlsGt()

The core function to translate a single text to the destination language, with parameter interpolation and fallback logic.

// Basic Usage
#whlsGt("Welcome to the application", "es", "text")#      // (Output: Bienvenido a la aplicación)

// With parameter interpolation
#whlsGt("Hello, Mr John Doe!", "fr", "text")#   // (Output: "Bonjour, Monsieur John Doe!")

Translate Full HTML (Recommended)

Translates a full HTML block or page while preserving the original markup. Only readable text nodes are sent to the translation provider, ensuring that HTML tags, attributes, and structure remain untouched.

This function is ideal for translating:

// Translate full HTML content
#whlsGtTranslate(includeContent(), "es")#

// Translate a raw HTML string
#whlsGtTranslate(
    text   = "<h1>Hello World</h1><p>Welcome to our site</p>",
    target = "fr"
)#

Tip: Wrap your full page output with whlsGtTranslate() to translate everything at once.

Get Current Language - whlsCurrentLanguage()

Gets the current application language from the Session, or the default language if not set.

language = whlsCurrentLanguage();       // "en"

Change Language - whlsChangeLanguage()

Sets the application language in Session and returns a boolean based on success.

// Change to Spanish
whlsChangeLanguage("es");

// Unsupported language
whlsChangeLanguage("jp");       // false

Get All Available Languages - whlsAvailableLanguages()

Returns an array of all configured available languages.

languages = whlsAvailableLanguages();       // ["en", "es", "fr"]

---

Best Practices

• Translate once per page, not per component
• Always use whlsGtTranslate() for full-page output
• Enable caching in production to reduce API usage
• Avoid translating dynamic fragments repeatedly

---

License

MIT

Author

Wheels-dev