Spring Boot i18n Sinhala Guide | Localize Your App in Multiple Languages

ආයුබෝවන් යාළුවනේ! කොහොමද ඔයාලට? අද අපි කතා කරන්න යන්නේ ගොඩක් වැදගත්, ඒ වගේම ඕනෑම නවීන software application එකකට අත්‍යවශ්‍ය දෙයක් ගැන – ඒ තමයි Internationalization (i18n), එහෙමත් නැත්නම් බහු භාෂා සහය (multi-language support) Spring Boot භාවිතයෙන් අපේ ඇප් එකකට එකතු කරගන්නේ කොහොමද කියලා.

හිතන්නකෝ, ඔයා ලංකාවේ ඉඳන් application එකක් හදනවා. ඒක පාවිච්චි කරන්න ලංකාවේ අය වගේම, එංගලන්තේ, ඇමරිකාවේ, ජපානේ වගේ රටවල අයත් ඉන්නවා කියලා. හැමෝටම තමන්ගේ භාෂාවෙන් application එකේ පණිවිඩ (messages) පෙන්නන්න පුළුවන් නම්, ඒක කොච්චර ලස්සනද? User experience එකත් වැඩි වෙනවා නේද? Spring Boot Internationalization කියන්නේ මේ වගේ වෙලාවට අපිට තියෙන නියම විසඳුමක්!

මේ tutorial එකෙන් අපි පහත දේවල් ගැන සවිස්තරව බලමු:

• Internationalization (i18n) කියන්නේ මොකක්ද සහ ඒක වැදගත් ඇයි?
• Spring Boot project එකකට i18n setup කරගන්න ආකාරය.
• විවිධ භාෂා වලට අදාළ පණිවිඩ (.properties files) ගබඩා කරන ආකාරය.
• Controller එකකින් සහ Thymeleaf template එකකින් මේ පණිවිඩ display කරන ආකාරය.
• පරිශීලකයාට භාෂාව මාරු කරන්න පුළුවන් විදියට functionality එකක් එකතු කරන ආකාරය.

ඉතින්, වැඩි කතා නැතුව වැඩේට බහිමු!

1. Internationalization (i18n) කියන්නේ මොකක්ද?

Internationalization කියන්නේ අපි හදන software application එක විවිධ භාෂා, කලාපීය විශේෂතා (regional specificities) සහ සංස්කෘතික සම්ප්‍රදායන් (cultural conventions) වලට අනුකූලව ක්‍රියාත්මක වෙන්න පුළුවන් විදියට design කරන එකට. 'i18n' කියලා කෙටියෙන් කියන්නේ 'Internationalization' කියන වචනේ 'i' අකුරටයි, 'n' අකුරටයි මැද අකුරු 18ක් තියෙන නිසා.

මේක Localization (l10n) කියන එකත් එක්ක වරදවා වටහාගන්න පුළුවන්. Localization කියන්නේ application එකක් නිශ්චිත භාෂාවකට සහ කලාපයකට ගැලපෙන විදියට හදන එක. උදාහරණයක් විදියට, i18n කියන්නේ විවිධ භාෂා සඳහා සහය දීමට application එක සූදානම් කිරීම නම්, l10n කියන්නේ Sinhala, English, Tamil වගේ භාෂා වලට අදාළව messages හදන එක. Spring Boot i18n කියන්නේ මේ දෙකටම උදව් වෙන framework එකක්.

ඇයි මේක වැදගත්? Global market එකේදී අපේ application එකට වැඩි පිරිසක් ළඟා කරගන්න, user satisfaction එක වැඩි කරන්න, ඒ වගේම අපේ brand එකට හොඳ නමක් හදාගන්න i18n අත්‍යවශ්‍යයි. ලංකාව වගේ බහු-භාෂා රටක නම්, මේක ඇත්තටම users ලාට ලොකු පහසුවක්.

2. Spring Boot එකේ i18n Setup කරමු

Spring Boot project එකකට i18n support එකතු කරන එක හිතන තරම් අමාරු නැහැ. අපිට මූලිකවම configure කරන්න ඕනෑ දේවල් තුනක් තියෙනවා:

1. MessageSource: මේකෙන් තමයි අපේ application එකට අවශ්‍ය messages (පණිවිඩ) අදාළ locale (භාෂාව) අනුව ලබා දෙන්නේ.
2. LocaleResolver: මේකෙන් තමයි දැනට user ගේ locale එක මොකක්ද කියලා තීරණය කරන්නේ.
3. LocaleChangeInterceptor: මේක optional වුවත්, user ට URL parameter එකක් හරහා locale එක මාරු කරන්න අවශ්‍ය නම් වැදගත් වෙනවා.

2.1. Maven Dependencies

ඔයා Spring Boot web application එකක් හදනවා නම්, basic i18n functionality එකට අමතර dependencies මොකුත් අවශ්‍ය නැහැ. Spring Boot Starter Web එක තිබ්බම ඇති.

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
    <!-- Other dependencies -->
</dependencies>

අපි මේ tutorial එකේදී web pages හදන්න Thymeleaf භාවිතා කරන නිසා, ඒ dependency එකත් එකතු කරගන්න.

2.2. i18n Configuration

දැන් අපි Spring Boot එකට මේ දේවල් configure කරමු. මේකට Configuration class එකක් හදාගන්න පුළුවන්. උදාහරණයක් විදියට, WebConfig.java කියලා class එකක් හදමු.

import org.springframework.context.MessageSource;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.support.ResourceBundleMessageSource;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import org.springframework.web.servlet.i18n.LocaleChangeInterceptor;
import org.springframework.web.servlet.i18n.SessionLocaleResolver;

import java.util.Locale;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    // 1. MessageSource Bean එක Configure කරමු
    @Bean
    public MessageSource messageSource() {
        ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource();
        messageSource.setBasenames("messages/messages"); // messages/messages_si.properties, messages/messages_en.properties
        messageSource.setDefaultEncoding("UTF-8");
        return messageSource;
    }

    // 2. LocaleResolver Bean එක Configure කරමු
    // user ගේ Locale එක session එකේ store කරනවා.
    @Bean
    public LocaleResolver localeResolver() {
        SessionLocaleResolver localeResolver = new SessionLocaleResolver();
        localeResolver.setDefaultLocale(Locale.ENGLISH); // default භාෂාව English
        return localeResolver;
    }

    // 3. LocaleChangeInterceptor එක Register කරමු
    // URL parameter එකක් (e.g., ?lang=si) හරහා Locale එක වෙනස් කරන්න ඉඩ දෙනවා.
    @Bean
    public LocaleChangeInterceptor localeChangeInterceptor() {
        LocaleChangeInterceptor lci = new LocaleChangeInterceptor();
        lci.setParamName("lang"); // 'lang' කියන parameter එකෙන් Locale එක වෙනස් කරන්න පුළුවන්.
        return lci;
    }

    // Interceptor එක Spring MVC එකට එකතු කරමු
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(localeChangeInterceptor());
    }
}

මේ code එකේ අපි කරපු දේවල් ටික පැහැදිලි කරමු:

• messageSource(): මේකෙන් අපි ResourceBundleMessageSource එකක් හදනවා. setBasenames("messages/messages") කියන්නේ අපේ පණිවිඩ files තියෙන්නේ src/main/resources/messages කියන folder එකේ, ඒ වගේම ඒවායේ නම messages.properties, messages_si.properties, messages_en.properties වගේ රටාවකට තියෙනවා කියන එක. setDefaultEncoding("UTF-8") කියන්නේ අපි Unicode characters (සිංහල අකුරු වගේ) පාවිච්චි කරන නිසා.
• localeResolver(): මේකෙන් අපි SessionLocaleResolver එකක් හදනවා. මේකෙන් user ගේ locale එක HTTP session එකේ store කරනවා. application එකට මුලින්ම access කරන user කෙනෙක්ට default විදියට English locale එක දෙනවා. (ඔබට CookieLocaleResolver එකක් භාවිතා කරන්නත් පුළුවන්, locale එක cookie එකක store කරන්න.)
• localeChangeInterceptor(): මේක හරිම වැදගත් component එකක්. URL parameter එකක් (අපේ code එකේ lang කියලා දීලා තියෙනවා) හරහා user ට locale එක මාරු කරන්න පුළුවන් වෙන්නේ මේක නිසයි. උදාහරණයක් විදියට, URL එකට ?lang=si කියලා එකතු කරලා Sinhala locale එකට මාරු වෙන්න පුළුවන්.
• addInterceptors(): අන්තිමට, අපි හදාගත්තු LocaleChangeInterceptor එක Spring MVC එකේ interceptor registry එකට එකතු කරනවා.

3. පණිවිඩ ගබඩා කරමු: .properties files

දැන් අපි application එකේ messages ගබඩා කරන .properties files හදාගමු. මේවා src/main/resources folder එක ඇතුළේ messages කියලා අලුත් folder එකක් හදලා ඒක ඇතුළේ තියන්න. අපි default, Sinhala සහ English භාෂා සඳහා files තුනක් හදමු.

src/main/resources/messages/messages.properties (Default - English)

# Default messages (can be English or fallback)
greeting.message=Hello World!
welcome.text=Welcome to our multi-language Spring Boot application!
language.label=Language

src/main/resources/messages/messages_en.properties (English)

# English messages
greeting.message=Hello World from English!
welcome.text=Welcome to our English Spring Boot application!
language.label=Language

src/main/resources/messages/messages_si.properties (සිංහල)

# Sinhala messages
greeting.message=ආයුබෝවන් ලෝකයට!
welcome.text=අපගේ බහු-භාෂා Spring Boot යෙදුමට ඔබව සාදරයෙන් පිළිගනිමු!
language.label=භාෂාව

මෙහිදී මතක තබාගත යුතු වැදගත් කරුණක් තමයි, keys (greeting.message වගේ) තුනෙහිම එක හා සමාන විය යුතුයි. values (Hello World! වගේ) විතරයි අදාළ භාෂාවට අනුව වෙනස් වෙන්නේ. UTF-8 encoding නිසා අපිට සිංහල අකුරු කෙලින්ම type කරන්න පුළුවන්.

4. Controller එකෙන් Message පෙන්නමු

දැන් අපි Spring Boot Controller එකක් හදමු, මේ messages access කරලා web page එකකට display කරන්න. අපි HomeController.java කියලා class එකක් හදමු.

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.MessageSource;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;

import java.util.Locale;

@Controller
public class HomeController {

    @Autowired
    private MessageSource messageSource;

    @GetMapping("/")
    public String home(Model model, Locale locale) {
        // MessageSource එකෙන් අදාළ locale එකට අනුව message එක ලබා ගන්නවා
        String greeting = messageSource.getMessage("greeting.message", null, locale);
        String welcome = messageSource.getMessage("welcome.text", null, locale);
        String langLabel = messageSource.getMessage("language.label", null, locale);

        model.addAttribute("greeting", greeting);
        model.addAttribute("welcome", welcome);
        model.addAttribute("languageLabel", langLabel);
        model.addAttribute("currentLocale", locale.getLanguage()); // දැනට තියෙන භාෂාව

        return "home"; // home.html template එකට යනවා
    }
}

මේ controller එකේදී අපි කරන්නේ:

• MessageSource එක @Autowired කරනවා.
• @GetMapping("/") එකේදී method එකට Locale locale කියලා parameter එකක් දීලා තියෙනවා. Spring එකෙන් මේ locale එක (අපේ SessionLocaleResolver එකෙන් තීරණය කරපු) අපිට automatically inject කරනවා.
• messageSource.getMessage("key", null, locale) කියන method එකෙන් අදාළ locale එකට ගැලපෙන message එක ලබා ගන්නවා. දෙවෙනි parameter එක null කරලා තියෙන්නේ dynamic arguments නැති නිසා.
• ලබාගත් messages ටික Model එකට add කරලා, home.html කියන template එක return කරනවා.

5. Front-end එකයි, Locale Change එකයි (Thymeleaf)

දැන් අපි Thymeleaf template එකක් හදමු, ඒකේ මේ messages display කරලා, භාෂාව මාරු කරන්න පුළුවන් links ටිකක් එකතු කරමු. src/main/resources/templates folder එක ඇතුළේ home.html කියලා file එකක් හදන්න.

<!DOCTYPE html>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Spring Boot i18n Guide</title>
    <style>
        body { font-family: Arial, sans-serif; margin: 20px; line-height: 1.6; background-color: #f4f4f4; color: #333; }
        .container { max-width: 800px; margin: auto; background: #fff; padding: 30px; border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.1); }
        h1, h2 { color: #0056b3; }
        .language-switcher a { margin-right: 15px; text-decoration: none; color: #007bff; }
        .language-switcher a:hover { text-decoration: underline; }
        .current-locale { font-weight: bold; color: #28a745; }
    </style>
</head>
<body>
    <div class="container">
        <h1 th:text="${greeting}">Default Greeting</h1>
        <p th:text="${welcome}">Default Welcome Text</p>

        <hr>

        <div class="language-switcher">
            <span th:text="${languageLabel}">Language:</span>
            <a th:href="@{/?lang=en}">English</a>
            <a th:href="@{/?lang=si}">සිංහල</a>
        </div>

        <p>Current Locale: <span class="current-locale" th:text="${currentLocale}">en</span></p>
    </div>
</body>
</html>

මේ HTML template එකේදී අපි Thymeleaf's th:text attribute එක පාවිච්චි කරලා Controller එකෙන් model එකට add කරපු messages display කරනවා. ඒ වගේම, language switcher එකේ links ටික බලන්න:

• <a th:href="@{/?lang=en}">English</a>
• <a th:href="@{/?lang=si}">සිංහල</a>

මේ links ක්ලික් කරාම, URL එකට ?lang=en හෝ ?lang=si කියලා parameter එකක් එකතු වෙනවා. අපේ LocaleChangeInterceptor එක මේ parameter එක අඳුරගෙන session එකේ locale එක අදාළ භාෂාවට මාරු කරනවා. ඊට පස්සේ page එක නැවත load වෙද්දී, අලුත් locale එකට අනුව messages display වෙනවා.

වැඩේ පටන් ගමු!

දැන් ඔයාට පුළුවන් Spring Boot application එක run කරන්න. Terminal එකේ mvn spring-boot:run කියලා command එක දෙන්න. ඊට පස්සේ, browser එකේ http://localhost:8080/ කියලා access කරන්න. ඔයාට default විදියට English messages පෙනේවි.

දැන් page එකේ තියෙන 'සිංහල' link එක ක්ලික් කරලා බලන්න. messages ටික සිංහලට මාරු වෙයි! ඒ වගේම 'English' link එක ක්ලික් කරලා ආයෙත් English වලට මාරු වෙන්න පුළුවන්.

නිගමනය (Conclusion)

ඉතින් යාළුවනේ, මේ tutorial එකෙන් අපි Spring Boot application එකකට Internationalization (i18n) functionality එකතු කරගන්න විදිය සරලවම ඉගෙන ගත්තා. MessageSource, LocaleResolver, LocaleChangeInterceptor කියන components හරහා කොහොමද විවිධ භාෂා සඳහා සහය ලබා දෙන්නේ කියලා ඔයාලට දැන් හොඳ අවබෝධයක් ඇති.

මේ feature එක ඔයාගේ application එකට එකතු කිරීමෙන් global audience එකක් වෙත ළඟා වෙන්නත්, user experience එක වැඩි දියුණු කරන්නත් පුළුවන්. ඒක ඔයාගේ application එක තවත් professional එකක් බවට පත් කරනවා!

දැන් ඔයාලත් මේක ඔයාලගේ project එකක implement කරලා බලන්න. මොනවා හරි ප්‍රශ්න තියෙනවා නම්, පහතින් comment එකක් දාන්න. ඔයාලගේ අත්දැකීම් ගැනත් අපිට කියන්න!

තවත් අලුත් tutorial එකකින් හමුවෙමු, හැමෝටම ජය!