Building SaaS Website #08: Localization (Multi-Language Website)

In this blog post, we explore an essential feature of modern web applications: localization. Creating a multilingual website allows you to reach a global audience and deliver a tailored user experience based on language preferences. Total.js provides a robust localization mechanism, making it easier to build and manage multilingual applications.

Here’s what we’ll cover in this post:

The notion of localization.
How localization works in client-server relations.
Initializing localization in Total.js to get or set client language preferences.
Translation string syntax.
File types that support localization.
Total.js language resource files and translations.
Free machine translation using Total.js’s online translator.

Let’s get started!

The Notion of Localization

Localization refers to the process of adapting a website or application to support multiple languages and regional preferences. It goes beyond translating text by ensuring cultural and contextual appropriateness. For web developers, this means creating tools to:

Detect user language preferences.
Serve translated content dynamically.
Support various file formats and ensure consistent functionality across languages.

A localized website provides a seamless and inclusive experience for users worldwide, enhancing accessibility and user satisfaction.

How Localization Works in Client-Server Relations

Localization in web development typically involves communication between the client (browser) and server. Here’s how it works:

Language Detection: The server identifies the user’s language preference using methods such as:
- Query parameters (e.g., ?language=en).
- Browser settings (Accept-Language header).
- User account preferences (if logged in).

Localized Content Delivery: Based on the detected language, the server fetches and serves the appropriate language resources.

Dynamic Rendering: Total.js localizes views and static .html files at compile time. Translated views are stored in memory, ensuring efficient delivery.

This seamless exchange ensures users receive content in their preferred language without extra effort on their part.

Initializing Localization in Total.js

To set up localization in a Total.js project, you need to define how the server determines the client’s language. This is done by registering a localization delegate that processes incoming requests.

Example:

/definitions/localization.js

LOCALIZE(function($) {
    // $.query: Retrieve from Query parameters
    // $.headers or $.req.language: Retrieve from Request headers
    // $.user: Retrieve from User object (if authenticated)

    // Return the language resource name (e.g., 'en', 'sk')
    return $.query.language || 'en';
});

This function retrieves the language preference from the query parameter language. If no preference is provided, it defaults to English (en).

Translation String Syntax

In Total.js, text intended for translation is wrapped in the @(text) markup. During localization, this text is replaced with its corresponding translation from the resource files.

Example in an HTML file:

@{title('@(TotalGPT Website)')}

<h1>@(Welcome to TotalGPT!)</h1>
<p>@(Experience seamless AI-powered solutions for your business.)</p>

If the localized text contains special characters like " or ', you must HTML-encode them to ensure proper usage in JavaScript or HTML.

File Types Supporting Localization

Localization in Total.js applies to the following file types:

Static .html files: Translated at compile time.
Views: Dynamic templates processed by the framework.

Each translated file is stored in memory for fast and efficient retrieval.

Total.js Language Resource Files and Translations

Total.js uses resource files (.resource) to store translations. These files are created by scanning the source code for text wrapped in @() and generating unique keys for each string.

Example with Updated HTML Code

/views/layout.html

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>@(TotalGPT Website)</title>

        <!-- Total.js visitor module for analytics -->
        <script src="/visitors.js"></script>

        <!-- JComponent library for enhanced UI interactions -->
        <link rel="stylesheet" href="//cdn.componentator.com/spa.min@19.css" />

        <!-- Import custom styles -->
        @{import('style.css')}
    </head>
    <body>
        <!-- Header -->
        <header class="header">
            <div class="link">
                <a href="/" class="logo">@(TotalGPT)</a>
                <a title="Chat on WhatsApp" href="https://wa.me/22655416464" target="_blank" id="whatsapp">
                    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><path d="M7.25361 18.4944L7.97834 18.917C9.189"></path></svg>
                </a>
            </div>
            <i class="ti ti-bars" id="menu-icon"></i>
            <nav class="navbar">
                <a href="/">@(Home)</a>
                <a href="/about" class="active">@(About)</a>
                <a href="/services">@(Services)</a>
                <a href="/pricing">@(Pricing)</a>
                <a href="/contact">@(Contact)</a>
                <a href="https://wa.me/22655416464" class="btn other-platform">@(WhatsApp)</a>
            </nav>
        </header>

        <!-- Main Content -->
        <main>
            @{body}
        </main>

        <!-- Footer -->
        <footer class="footer">
            <div class="footer-text">
                <p>@(Copyright © 2025 by Total.js | All Rights Reserved.)</p>
            </div>
            <div class="footer-top">
                <a href="#home"><i class="ti ti-arrow-up"></i></a>
            </div>
        </footer>

        <!-- Scripts -->
        <script src="/js/script.js"></script>
        <script src="https://unpkg.com/scrollreveal"></script>
        <script src="https://unpkg.com/typed.js@2.0.16/dist/typed.umd.js"></script>
    </body>
</html>

Free Machine Translation with Total.js Translator

Total.js offers an online translator tool for free machine translation of resource files. This tool simplifies the translation process and ensures consistency across languages.

Try it here: Total.js Translator

Features:

Upload resource files for translation.
Download translated files in the same format.

By implementing localization in Total.js, you can create a truly global website that adapts to user preferences. This improves user engagement and accessibility, ensuring your application stands out in a competitive market.

Stay tuned for the next episode of our TotalGPT SaaS Website series!