DEV Community: OnlyCoiners

How to Deploy a Node.js App to DigitalOcean Droplet or Other Linux VM

OnlyCoiners — Fri, 20 Dec 2024 09:20:02 +0000

Deploying a Node.js application to a DigitalOcean Droplet or any Linux virtual machine is important to make your project online.

This guide uses SSH, GitHub, PM2, and Nginx for efficient and reliable deployment to deploy a Node.js app to DigitalOcean.

You can use it for other VM also.

We will use PM2 here mostly because it is already pre installed and working for the default set the DigitalOcena gives.

But, there are some reasons to use PM2 as well.

PM2 is a powerful process manager for Node.js applications, designed to make your life easier when running and managing production apps. It goes beyond simply starting your application—it provides a suite of features that ensure your app runs smoothly and reliably, even in the most demanding environments.

We have a WhatsApp group for job posts using the process described in this post.

You can join it for latest jobs. You can also find and post jobs on our job board.

Why You Should Use PM2

Automatic Restart

PM2 automatically restarts your app if it crashes, ensuring zero downtime. This is a lifesaver for production environments where reliability is critical.
Process Management

It allows you to manage multiple applications on a single server effortlessly. With simple commands like pm2 start, stop, restart, and delete, you have full control over your processes.
Built-In Monitoring

PM2 provides real-time monitoring of your app's performance, showing CPU and memory usage. This helps you identify bottlenecks and optimize your app.
Startup Scripts

When you reboot your server, PM2 ensures your apps start automatically by generating a startup script tailored to your system.
Log Management

PM2 consolidates logs from all your applications into one place. You can view, tail, or clear logs with a single command, making debugging much more manageable.
Cluster Mode

Want to utilize all CPU cores on your server? PM2's cluster mode makes it easy to scale your app horizontally, maximizing performance.
Ease of Use

With a clean and intuitive CLI, PM2 is beginner-friendly while still offering advanced features for experienced developers.
Cross-Platform

PM2 works seamlessly on various operating systems, including Linux, macOS, and Windows, making it a versatile choice for any environment.

PM2 has Its robust features and simplicity make it a go-to solution for production deployments. Whether you're scaling a startup app or managing a high-traffic application, PM2 ensures stability and provides peace of mind. It empowers developers to focus on building features instead of worrying about process management, making it an invaluable tool in your arsenal.

Prerequisites

Node.js Application: A ready-to-deploy Node.js app.
DigitalOcean Droplet: Set up with Ubuntu or similar.
SSH Access: Configured for secure login.
Nginx: For reverse proxy setup.

If you don't have any Node.js app to test, you can use our example.

$git clone https://github.com/OnlyCoiner/digitalocean_deployment_examples.git
$cd node
$yarn
$yarn test
$yarn dev

Set Up SSH and GitHub

Create the Droplet

Create an account or log into DigitalOcean and create a Node.js Droplet. You can use its console and use the commands below.

Use its default nodesource_setup.sh script and you will have most of requirements ready including git, node, yarn or npm etc. Otherwise, you can install them manually as you did in your laptop.

./nodesource_setup.sh

Transfer SSH Key

Save your SSH key ~/.ssh/your_private_key to the Droplet or your VM to download your project from GitHub or others with $git pull command.

You can make one here https://github.com/settings/keys for GitHub if you don't have it yet.

$scp ~/.ssh/your_private_key root@<your-droplet-ip>:~/.ssh/
$chmod 600 ~/.ssh/your_private_key

Configure SSH Access

Edit the SSH config file on your server.

This way, you can also push your updates to a git repository if you want to.

$vim ~/.ssh/config

Edit with the text below.

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/your_private_key
  AddKeysToAgent yes

Clone the Repository

Clone your app from GitHub.

git clone https://github.com/OnlyCoiners/digitalocean_deployment_examples.git

Use PM2 to Manage Your Node.js App

Stop Default Apps

DigitalOcean’s default Node.js app may be running. Stop and delete it first.

$pm2 list
$pm2 stop hello
$pm2 delete hello
$pm2 save
$pm2 save --force

Start Your Node.js App

Depending on your setup, use one of the following commands

$pm2 start npx --name onlycoiners_node -- tsx ./src/index.ts

You will see some logs from pm2 and other messages in your console.

OnlyCoiners server is running on port 8888

Save and Set Up PM2

$pm2 list
$pm2 save
$pm2 startup

Use $pm2 list to see if your app is working and $pm2 save to save your updates.

Use $pm2 startup to make your app working after you close your SSH connection to your droplet or VM.

Check Logs

$pm2 logs
$pm2 logs onlycoiners_node

Your app might not be working at first attempt. Use $pm2 logs or $pm2 logs <yourappname> to debug.

Configure Nginx as a Reverse Proxy

Edit Nginx Configuration

$sudo vim /etc/nginx/sites-available/default

Edit it to use the code snippet below instead and the port number for your app.

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    root /var/www/html;
    index index.html index.htm index.nginx-debian.html;

    server_name _;

    location ^~ /assets/ {
        gzip_static on;
        expires 12h;
        add_header Cache-Control public;
    }

    location / {
        proxy_http_version 1.1;
        proxy_cache_bypass $http_upgrade;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_pass http://localhost:8888;
    }
}

This way, you will be able to curl to the IP for your project directly instead of assining your port number.

Restart Nginx

After the update, restart your nginx for your update to work.

$sudo systemctl restart nginx

Test Your Setup

Verify Nginx and Node.js

Use curl to test whenever you make updates so you can test if it is working or not.

$curl localhost:8888  # Node.js app
$curl localhost       # Nginx reverse proxy

$curl <your-server-ip>

They should show all same results with "Create, Earn and Network with OnlyCoiners! Join us https://www.onlycoiners.com" or others depedning on your project.

Use $curl <your-server-ip> after you close SSH connectio to your droplet or VM to see if the app is still working after you close the connection.

Check PM2 Status

Optionally, you can test PM2 is managing your app properly with these again.

$pm2 list
$pm2 logs

Troubleshooting Tips

Check application logs for errors:

$pm2 logs onlycoiners_node

Ensure your SSH key and Nginx configuration are correct.

Conclusion

Deploying a Node.js app to DigitalOcean or a Linux VM with PM2 and Nginx ensures reliability and scalability. By following this guide, you’ll be able to make your project work with DigitalOcean or other Linux virtual machines.

Como Implantar um Aplicativo Node.js em um Droplet do DigitalOcean e outra VM

OnlyCoiners — Fri, 20 Dec 2024 09:18:03 +0000

Implantar uma aplicação Node.js em um Droplet da DigitalOcean ou em qualquer máquina virtual Linux é importante para colocar seu projeto online.

Este guia utiliza SSH, GitHub, PM2 e Nginx para uma implantação eficiente e confiável de uma aplicação Node.js na DigitalOcean.

Você também pode usá-lo para outras máquinas virtuais.

Usaremos o PM2 principalmente porque já está pré-instalado e funcionando com a configuração padrão fornecida pela DigitalOcean.

No entanto, há também razões para usar o PM2.

PM2 é um poderoso gerenciador de processos para aplicações Node.js, projetado para facilitar sua vida ao executar e gerenciar aplicativos em produção. Vai além de simplesmente iniciar sua aplicação: fornece um conjunto de recursos que garantem que sua aplicação funcione de forma tranquila e confiável, mesmo nos ambientes mais exigentes.

Temos um grupo no WhatsApp para postagens de empregos usando o processo descrito neste post.

Você pode participar para ver as últimas vagas. Você também pode encontrar e postar empregos no nosso quadro de empregos.

Por que usar o PM2

Reinício Automático

O PM2 reinicia automaticamente sua aplicação caso ela falhe, garantindo zero tempo de inatividade. Isso é essencial em ambientes de produção onde a confiabilidade é crítica.
Gerenciamento de Processos

Permite gerenciar várias aplicações em um único servidor de forma fácil. Com comandos simples como pm2 start, stop, restart e delete, você tem controle total sobre seus processos.
Monitoramento Integrado

O PM2 fornece monitoramento em tempo real do desempenho da sua aplicação, exibindo o uso de CPU e memória. Isso ajuda a identificar gargalos e otimizar sua aplicação.
Scripts de Inicialização

Quando você reinicia seu servidor, o PM2 garante que suas aplicações iniciem automaticamente gerando um script de inicialização adaptado ao seu sistema.
Gerenciamento de Logs

O PM2 consolida logs de todas as suas aplicações em um único local. Você pode visualizar, seguir ou limpar logs com um único comando, tornando a depuração muito mais gerenciável.
Modo de Cluster

Quer utilizar todos os núcleos de CPU do seu servidor? O modo de cluster do PM2 facilita a escalabilidade horizontal da sua aplicação, maximizando o desempenho.
Fácil de Usar

Com uma CLI limpa e intuitiva, o PM2 é amigável para iniciantes e ainda oferece recursos avançados para desenvolvedores experientes.
Multiplataforma

O PM2 funciona perfeitamente em vários sistemas operacionais, incluindo Linux, macOS e Windows, tornando-o uma escolha versátil para qualquer ambiente.

O PM2 possui recursos robustos e simplicidade que o tornam uma solução preferida para implantações em produção. Seja escalando um aplicativo inicial ou gerenciando uma aplicação de alto tráfego, o PM2 garante estabilidade e proporciona tranquilidade. Ele capacita os desenvolvedores a focarem na criação de recursos em vez de se preocuparem com o gerenciamento de processos, tornando-se uma ferramenta inestimável no seu arsenal.

Pré-requisitos

Aplicação Node.js: Uma aplicação Node.js pronta para implantação.
Droplet da DigitalOcean: Configurado com Ubuntu ou similar.
Acesso SSH: Configurado para login seguro.
Nginx: Para configuração de proxy reverso.

Se você não tem nenhuma aplicação Node.js para testar, pode usar nosso exemplo.

$git clone https://github.com/OnlyCoiner/digitalocean_deployment_examples.git
$cd node
$yarn
$yarn test
$yarn dev

Configurar SSH e GitHub

Criar o Droplet

Crie uma conta ou faça login no DigitalOcean e crie um Droplet para Node.js. Você pode usar o console e executar os comandos abaixo.

Use o script padrão nodesource_setup.sh e você terá a maioria dos requisitos prontos, incluindo git, node, yarn ou npm, etc. Caso contrário, você pode instalá-los manualmente, como fez no seu laptop.

./nodesource_setup.sh

Transferir a chave SSH

Salve sua chave SSH ~/.ssh/your_private_key no Droplet ou sua máquina virtual para baixar seu projeto do GitHub ou outros com o comando $git pull.

Você pode criar uma aqui https://github.com/settings/keys para o GitHub, caso ainda não tenha.

$scp ~/.ssh/your_private_key root@<your-droplet-ip>:~/.ssh/
$chmod 600 ~/.ssh/your_private_key

Configurar o acesso SSH

Edite o arquivo de configuração SSH no seu servidor.

Dessa forma, você também pode enviar suas atualizações para um repositório git, se desejar.

$vim ~/.ssh/config

Edite com o texto abaixo.

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/your_private_key
  AddKeysToAgent yes

Clonar o repositório

Clone sua aplicação do GitHub.

git clone https://github.com/OnlyCoiners/digitalocean_deployment_examples.git

Usar o PM2 para gerenciar sua aplicação Node.js

Parar aplicações padrão

A aplicação Node.js padrão da DigitalOcean pode estar em execução. Pare-a e exclua-a primeiro.

$pm2 list
$pm2 stop hello
$pm2 delete hello
$pm2 save
$pm2 save --force

Iniciar sua aplicação Node.js

Dependendo da sua configuração, use um dos comandos abaixo

$pm2 start npx --name onlycoiners_node -- tsx ./src/index.ts

Você verá alguns logs do pm2 e outras mensagens no seu console.

O servidor da OnlyCoiners está rodando na porta 8888

Salvar e configurar o PM2

$pm2 list
$pm2 save
$pm2 startup

Use $pm2 list para verificar se sua aplicação está funcionando e $pm2 save para salvar suas atualizações.

Use $pm2 startup para que sua aplicação continue funcionando após fechar sua conexão SSH com o droplet ou máquina virtual.

Verificar logs

$pm2 logs
$pm2 logs onlycoiners_node

Sua aplicação pode não funcionar na primeira tentativa. Use $pm2 logs ou $pm2 logs <yourappname> para depurar.

Configurar o Nginx como proxy reverso

Editar configuração do Nginx

$sudo vim /etc/nginx/sites-available/default

Edite para usar o trecho de código abaixo e inclua o número da porta da sua aplicação.

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    root /var/www/html;
    index index.html index.htm index.nginx-debian.html;

    server_name _;

    location ^~ /assets/ {
        gzip_static on;
        expires 12h;
        add_header Cache-Control public;
    }

    location / {
        proxy_http_version 1.1;
        proxy_cache_bypass $http_upgrade;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_pass http://localhost:8888;
    }
}

Dessa forma, você poderá usar curl para o IP do seu projeto diretamente, em vez de atribuir o número da porta.

Reiniciar o Nginx

Após a atualização, reinicie seu nginx para que sua atualização funcione.

$sudo systemctl restart nginx

Testar sua configuração

Verificar Nginx e Node.js

Use curl para testar sempre que fizer atualizações e verificar se está funcionando ou não.

$curl localhost:8888  # Aplicação Node.js
$curl localhost       # Proxy reverso Nginx

$curl <your-server-ip>

Eles devem mostrar os mesmos resultados com "Crie, Ganhe e Conecte-se com OnlyCoiners! Junte-se a https://www.onlycoiners.com" ou outros dependendo do seu projeto.

Use $curl <your-server-ip> após fechar a conexão SSH com o droplet ou máquina virtual para verificar se a aplicação ainda está funcionando após fechar a conexão.

Verificar status do PM2

Opcionalmente, você pode testar se o PM2 está gerenciando sua aplicação corretamente com esses comandos novamente.

$pm2 list
$pm2 logs

Dicas para solução de problemas

Verifique os logs da aplicação para erros:

$pm2 logs onlycoiners_node

Certifique-se de que sua chave SSH e configuração do Nginx estão corretas.

Conclusão

Implantar uma aplicação Node.js na DigitalOcean ou em uma máquina virtual Linux com PM2 e Nginx garante confiabilidade e escalabilidade. Seguindo este guia, você poderá fazer seu projeto funcionar com a DigitalOcean ou outras máquinas virtuais Linux.

Cómo Implementar una Aplicación Node.js en un Droplet de DigitalOcean y otra VM

OnlyCoiners — Fri, 20 Dec 2024 09:16:31 +0000

Implementar una aplicación Node.js en un Droplet de DigitalOcean o en cualquier máquina virtual Linux es importante para hacer que tu proyecto esté en línea.

Esta guía utiliza SSH, GitHub, PM2 y Nginx para un despliegue eficiente y confiable de una aplicación Node.js en DigitalOcean.

También puedes usarla para otras máquinas virtuales.

Usaremos PM2 principalmente porque ya está preinstalado y funcionando con la configuración predeterminada que ofrece DigitalOcean.

Sin embargo, también hay razones para usar PM2.

PM2 es un gestor de procesos poderoso para aplicaciones Node.js, diseñado para facilitar la vida al ejecutar y gestionar aplicaciones en producción. Va más allá de simplemente iniciar tu aplicación: proporciona una suite de funciones que garantizan que tu aplicación funcione de manera fluida y confiable, incluso en los entornos más exigentes.

Tenemos un grupo de WhatsApp para ofertas de empleo usando el proceso descrito en este post.

Puedes unirte para ver las últimas ofertas de empleo. También puedes encontrar y publicar empleos en nuestro tablón de empleo.

Por qué deberías usar PM2

Reinicio automático

PM2 reinicia automáticamente tu aplicación si se bloquea, asegurando cero tiempo de inactividad. Esto es crucial en entornos de producción donde la confiabilidad es crítica.
Gestión de procesos

Permite gestionar múltiples aplicaciones en un solo servidor fácilmente. Con comandos simples como pm2 start, stop, restart y delete, tienes control total sobre tus procesos.
Monitorización integrada

PM2 proporciona monitorización en tiempo real del rendimiento de tu aplicación, mostrando el uso de CPU y memoria. Esto te ayuda a identificar cuellos de botella y optimizar tu aplicación.
Scripts de inicio

Cuando reinicias tu servidor, PM2 asegura que tus aplicaciones se inicien automáticamente generando un script de inicio adaptado a tu sistema.
Gestión de registros

PM2 consolida los registros de todas tus aplicaciones en un solo lugar. Puedes ver, seguir o borrar registros con un solo comando, haciendo que la depuración sea mucho más manejable.
Modo clúster

¿Quieres utilizar todos los núcleos de CPU de tu servidor? El modo clúster de PM2 facilita la ampliación horizontal de tu aplicación, maximizando el rendimiento.
Facilidad de uso

Con una CLI limpia e intuitiva, PM2 es fácil de usar para principiantes y ofrece funciones avanzadas para desarrolladores experimentados.
Multiplataforma

PM2 funciona perfectamente en varios sistemas operativos, incluidos Linux, macOS y Windows, lo que lo convierte en una opción versátil para cualquier entorno.

PM2 tiene características robustas y simplicidad que lo convierten en una solución preferida para despliegues en producción. Ya sea que estés ampliando una aplicación de inicio o gestionando una aplicación de alto tráfico, PM2 garantiza estabilidad y proporciona tranquilidad. Empodera a los desarrolladores para centrarse en construir funciones en lugar de preocuparse por la gestión de procesos, convirtiéndose en una herramienta invaluable en tu arsenal.

Requisitos previos

Aplicación Node.js: Una aplicación Node.js lista para desplegar.
Droplet de DigitalOcean: Configurado con Ubuntu o similar.
Acceso SSH: Configurado para inicio de sesión seguro.
Nginx: Para la configuración de proxy inverso.

Si no tienes ninguna aplicación Node.js para probar, puedes usar nuestro ejemplo.

$git clone https://github.com/OnlyCoiner/digitalocean_deployment_examples.git
$cd node
$yarn
$yarn test
$yarn dev

Configurar SSH y GitHub

Crear el Droplet

Crea una cuenta o inicia sesión en DigitalOcean y crea un Droplet para Node.js. Puedes usar su consola y ejecutar los comandos a continuación.

Usa su script predeterminado nodesource_setup.sh y tendrás la mayoría de los requisitos listos, incluidos git, node, yarn o npm, etc. De lo contrario, puedes instalarlos manualmente como lo hiciste en tu laptop.

./nodesource_setup.sh

Transferir clave SSH

Guarda tu clave SSH ~/.ssh/your_private_key en el Droplet o tu máquina virtual para descargar tu proyecto desde GitHub u otros con el comando $git pull.

Puedes crear una aquí https://github.com/settings/keys para GitHub si aún no la tienes.

$scp ~/.ssh/your_private_key root@<your-droplet-ip>:~/.ssh/
$chmod 600 ~/.ssh/your_private_key

Configurar acceso SSH

Edita el archivo de configuración SSH en tu servidor.

De esta manera, también puedes enviar tus actualizaciones a un repositorio git si lo deseas.

$vim ~/.ssh/config

Edita con el texto a continuación.

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/your_private_key
  AddKeysToAgent yes

Clonar el repositorio

Clona tu aplicación desde GitHub.

git clone https://github.com/OnlyCoiners/digitalocean_deployment_examples.git

Usar PM2 para gestionar tu aplicación Node.js

Detener aplicaciones predeterminadas

La aplicación Node.js predeterminada de DigitalOcean puede estar ejecutándose. Detenla y elimínala primero.

$pm2 list
$pm2 stop hello
$pm2 delete hello
$pm2 save
$pm2 save --force

Iniciar tu aplicación Node.js

Dependiendo de tu configuración, usa uno de los siguientes comandos

$pm2 start npx --name onlycoiners_node -- tsx ./src/index.ts

Verás algunos registros de pm2 y otros mensajes en tu consola.

El servidor de OnlyCoiners está funcionando en el puerto 8888

Guardar y configurar PM2

$pm2 list
$pm2 save
$pm2 startup

Usa $pm2 list para ver si tu aplicación está funcionando y $pm2 save para guardar tus actualizaciones.

Usa $pm2 startup para que tu aplicación siga funcionando después de cerrar tu conexión SSH al droplet o máquina virtual.

Verificar registros

$pm2 logs
$pm2 logs onlycoiners_node

Tu aplicación podría no estar funcionando en el primer intento. Usa $pm2 logs o $pm2 logs <yourappname> para depurar.

Configurar Nginx como proxy inverso

Editar configuración de Nginx

$sudo vim /etc/nginx/sites-available/default

Edita para usar el fragmento de código a continuación e incluye el número de puerto de tu aplicación.

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    root /var/www/html;
    index index.html index.htm index.nginx-debian.html;

    server_name _;

    location ^~ /assets/ {
        gzip_static on;
        expires 12h;
        add_header Cache-Control public;
    }

    location / {
        proxy_http_version 1.1;
        proxy_cache_bypass $http_upgrade;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_pass http://localhost:8888;
    }
}

De esta manera, podrás usar curl para la IP de tu proyecto directamente en lugar de asignar el número de puerto.

Reiniciar Nginx

Después de la actualización, reinicia tu nginx para que funcione tu actualización.

$sudo systemctl restart nginx

Probar tu configuración

Verificar Nginx y Node.js

Usa curl para probar cada vez que hagas actualizaciones y verificar si está funcionando o no.

$curl localhost:8888  # Aplicación Node.js
$curl localhost       # Proxy inverso Nginx

$curl <your-server-ip>

Deberían mostrar los mismos resultados con "¡Crea, gana y conecta con OnlyCoiners! Únete a https://www.onlycoiners.com" u otros dependiendo de tu proyecto.

Usa $curl <your-server-ip> después de cerrar la conexión SSH al droplet o máquina virtual para verificar si la aplicación sigue funcionando después de cerrar la conexión.

Comprobar estado de PM2

Opcionalmente, puedes probar que PM2 está gestionando tu aplicación correctamente con estos comandos nuevamente.

$pm2 list
$pm2 logs

Consejos para solución de problemas

Verifica los registros de la aplicación para errores:

$pm2 logs onlycoiners_node

Asegúrate de que tu clave SSH y configuración de Nginx sean correctas.

Conclusión

Implementar una aplicación Node.js en DigitalOcean o una máquina virtual Linux con PM2 y Nginx garantiza confiabilidad y escalabilidad. Siguiendo esta guía, podrás hacer que tu proyecto funcione con DigitalOcean u otras máquinas virtuales Linux.

Manera simple de agregar soporte i18n en Rust con ejemplos y pruebas

OnlyCoiners — Fri, 25 Oct 2024 10:35:16 +0000

La localización es crucial para el desarrollo de software moderno. Al soportar
múltiples idiomas, las aplicaciones pueden llegar a una audiencia más amplia y
volverse más inclusivas, alineándose con la misión de OnlyCoiners.

Sin embargo, gestionar traducciones de manera eficiente en un entorno multi-hilo
puede ser un desafío. En este post, exploraremos cómo aprovechar OnceCell y
Mutex de Rust para manejar traducciones almacenadas en archivos JSON,
almacenándolas en memoria para facilitar la localización efectiva en toda la
aplicación.

Podrías preguntarte por qué no utilizamos una solución ya establecida como
rust-i18n. Queríamos crear una versión equivalente al fragmento de código
Python implementado en nuestro servidor FastAPI, como se describe
en este post,
para reutilizar archivos de traducción y simplificar el proceso de reescribir
parte del código Python en nuestro servidor Rust OnlyCoiners API server.

Puedes probarlo en producción aquí.

Puedes crear un token de API aquí primero
después de crear una cuenta en OnlyCoiners.

Si tu empresa busca contratar a un desarrollador de Rust o brindar soporte a otra
organización que utilice Rust en producción, considera publicar una oferta de
trabajo en OnlyCoiners.

Encuentra y publica trabajos de Rust en nuestro tablón de empleos.

Contáctanos para cualquier consulta, estaremos encantados
de ofrecer a ti y a tu empresa descuentos exclusivos y otros beneficios si estás contratando o quieres una colaboración con nuestra empresa..

Sientete libre de unirte a nuestra plataforma si eres un Rustacean, ¡todos son bienvenidos
y también contratamos!

Puedes leer versión EN ou PT se quieres.

Puedes leer publicación original en nuestro sitio web.

Fragmento completo de código para translator.rs

Antes de continuar, nos gustaría presentar el fragmento completo de
código en Rust para la estructura Translator, diseñado para facilitar la
internacionalización dentro de tu base de código en Rust.

use once_cell::sync::OnceCell;
use serde_json;
use std::collections::HashMap;
use std::sync::Mutex;
use std::{env, fs};

// 1. Global static storage for translation modules
static TRANSLATIONS: OnceCell<Mutex<HashMap<String, HashMap<String, HashMap<String, String>>>>> =
    OnceCell::new();

pub struct Translator {
    lang: String,
}

impl Translator {
    // 2. Initialize the translator with a language
    pub fn new(lang: &str) -> Self {
        // Ensure translations are loaded once
        let _ = TRANSLATIONS.get_or_init(|| Mutex::new(HashMap::new()));
        Translator {
            lang: lang.to_string(),
        }
    }

    // 3. Load translations from files or other sources
    fn load_translation_module(
        &self,
        file_key: &str,
    ) -> Option<HashMap<String, HashMap<String, String>>> {
        let mut translations = TRANSLATIONS.get().unwrap().lock().unwrap();

        // Get the current working directory and construct the full path dynamically
        let current_dir = env::current_dir().unwrap();
        let module_path =
            current_dir.join(format!("src/translations/{}/{}.json", self.lang, file_key));

        // If translation is already loaded, return a cloned version
        if let Some(file_translations) = translations.get(file_key) {
            return Some(file_translations.clone());
        }

        // Load the translation file - error.json
        match fs::read_to_string(module_path) {
            Ok(content) => {
                // Parse the JSON into a nested HashMap - error -> common -> internal_server_error
                let file_translations: HashMap<String, HashMap<String, String>> =
                    serde_json::from_str(&content).unwrap_or_default();

                translations.insert(file_key.to_string(), file_translations.clone());
                Some(file_translations)
            }
            Err(e) => {
                tracing::error!("Error loading translation file - {}", e);
                None
            }
        }
    }

    // 4. Translate based on key and optional variables
    pub fn t(&self, key: &str, variables: Option<HashMap<&str, &str>>) -> String {
        let parts: Vec<&str> = key.split('.').collect();
        let file_key = parts.get(0).unwrap_or(&""); // "error"
        let section_key = parts.get(1).unwrap_or(&""); // "common"
        let translation_keys = &parts[2..]; // "INTERNAL_SERVER_ERROR"

        // Load the correct translation module (e.g., "error.json")
        if let Some(translation_module) = self.load_translation_module(file_key) {
            if let Some(section) = translation_module.get(*section_key) {
                let mut current_value: Option<&String> = None;

                // Traverse the translation keys to get the final string value
                for translation_key in translation_keys {
                    if current_value.is_none() {
                        // At the beginning, current_value is None, so we access the section (a HashMap)
                        if let Some(next_value) = section.get(*translation_key) {
                            current_value = Some(next_value);
                        } else {
                            return format!("Key '{}' not found in '{}' locale", key, self.lang);
                        }
                    }
                }

                // At this point, current_value should be a &String
                if let Some(translation_string) = current_value {
                    let mut translated_text = translation_string.clone();

                    // Handle variables if present
                    if let Some(variables) = variables {
                        for (variable, value) in variables {
                            let variable_format = format!("{{{}}}", variable);
                            translated_text = translated_text.replace(&variable_format, value);
                        }
                    }
                    translated_text
                } else {
                    format!("Key '{}' not found in '{}' locale", key, self.lang)
                }
            } else {
                format!(
                    "Section '{}' not found in '{}' locale",
                    section_key, self.lang
                )
            }
        } else {
            format!("Module '{}' not found for '{}' locale", file_key, self.lang)
        }
    }
}

¿Por qué usar almacenamiento estático para traducciones?

Al trabajar en aplicaciones multi-hilo, manejar datos globales requiere
especial cuidado. Sin la sincronización adecuada, podrías enfrentar
condiciones de carrera, fallos u otros problemas. Rust ofrece herramientas
como OnceCell y Mutex para resolver estos problemas de manera segura.

OnceCell garantiza que un valor se inicialice solo una vez y
proporciona acceso a él entre los hilos. Mutex garantiza acceso seguro y
mutable a los datos compartidos entre hilos, bloqueando el acceso cuando un
hilo está leyendo o escribiendo.

Al combinar estos dos, podemos crear un almacenamiento global estático que
almacena en caché los archivos de traducción en memoria, para que se carguen
una vez y se reutilicen durante toda la vida útil del programa. Este enfoque
evita cargar repetidamente archivos desde el disco y garantiza que las
traducciones se manejen de manera segura en un entorno concurrente.

Explicación del Código

Vamos a sumergirnos en el código que impulsa este sistema de traducción.
Utiliza una combinación de OnceCell, Mutex y un HashMap anidado para
cargar y almacenar traducciones de archivos JSON. Una vez que se carga un
archivo, se almacena en memoria y se reutiliza para solicitudes posteriores.

1. Almacenamiento Global de Traducciones

Los datos de traducción se almacenan en una variable estática global,
TRANSLATIONS, que utiliza OnceCell y Mutex para garantizar que los datos
sean seguros para hilos y se inicialicen solo una vez. La estructura del
HashMap permite organizar las traducciones de manera jerárquica.

El primer nivel almacena traducciones por clave de archivo, como error.json.
El segundo nivel agrupa traducciones por clave de sección, como common.
El tercer nivel almacena los pares clave-valor de la traducción real.

use once_cell::sync::OnceCell;
use std::collections::HashMap;
use std::sync::Mutex;

static TRANSLATIONS: OnceCell<Mutex<HashMap<String, HashMap<String, HashMap<String, String>>>>> =
    OnceCell::new();

Aquí está cómo funciona el HashMap anidado:

Clave de archivo, como "error", apunta a un mapa de claves de sección.
Cada clave de sección, como "common", contiene las cadenas de traducción, organizadas por claves como "internal_server_error", con mensajes correspondientes, como "Error interno del servidor", como puedes ver en el archivo JSON utilizado en producción en el servidor de API de OnlyCoiners.

src/translations/en/error.json

{
  "common": {
    "internal_server_error": "Internal server error",
    "not_authorized": "You are not authorized to use this resource",
    "not_found": "{resource} not found"
  },
  "token": {
    "no_api_user_token": "API-USER-TOKEN header is not included",
    "invalid_api_user_token": "API-USER-TOKEN header is not valid",
    "no_api_admin_token": "API-ADMIN-TOKEN header is not included",
    "unable_to_read_api_token": "Unable to read API Token"
  },
  "database": {
    "unable_to_query_database": "Unable to query database"
  }
}

2. Inicializando el Translator

La estructura Translator representa un objeto vinculado a un idioma específico,
como "en" para inglés o "pt" para portugués. Cuando creamos una instancia
de Translator, la variable global TRANSLATIONS se inicializa, en caso de
que aún no lo haya sido.

pub struct Translator {
    lang: String,
}

impl Translator {
    pub fn new(lang: &str) -> Self {
        let _ = TRANSLATIONS.get_or_init(|| Mutex::new(HashMap::new()));
        Translator {
            lang: lang.to_string(),
        }
    }
}

Esto garantiza que el almacenamiento global para traducciones esté configurado y
listo para ser utilizado. El campo lang en la estructura Translator almacena
el código del idioma, como "en" para inglés o "es" para español, y se usa
al cargar archivos de traducción.

3. Cargando Archivos de Traducción

La función load_translation_module es responsable de cargar los datos de
traducción de un archivo, como src/translations/en/error.json. Lee el
archivo JSON, analiza los datos y los almacena en el mapa global
TRANSLATIONS para uso futuro. Si el archivo ya ha sido cargado, simplemente
devuelve la versión almacenada en caché.

use std::{env, fs};

fn load_translation_module(
    &self,
    file_key: &str,
) -> Option<HashMap<String, HashMap<String, String>>> {
    let mut translations = TRANSLATIONS.get().unwrap().lock().unwrap();
    let current_dir = env::current_dir().unwrap();
    let module_path =
        current_dir.join(format!("src/translations/{}/{}.json", self.lang, file_key));

    if let Some(file_translations) = translations.get(file_key) {
        return Some(file_translations.clone());
    }

    match fs::read_to_string(module_path) {
        Ok(content) => {
            let file_translations: HashMap<String, HashMap<String, String>> =
                serde_json::from_str(&content).unwrap_or_default();
            translations.insert(file_key.to_string(), file_translations.clone());
            Some(file_translations)
        }
        Err(e) => {
            tracing::error!("Error loading translation file - {}", e);
            None
        }
    }
}

Esta función hace lo siguiente:

Verifica si el archivo ya está cargado: Si lo está, devuelve los datos almacenados en caché en el mapa TRANSLATIONS.
Carga el archivo de traducción: Si el archivo aún no ha sido cargado, lee el archivo JSON en la ruta src/translations/{lang}/{file}.json, analiza el contenido en un HashMap y lo almacena en memoria.
Maneja errores: Si el archivo no se puede leer, por ejemplo, si no existe, se registra un mensaje de error y la función devuelve None.

4. Traduciendo Claves con Variables

Una vez que las traducciones están cargadas, puedes recuperarlas usando la
función t. Esta función recibe una clave, que es una cadena separada por
puntos. Por ejemplo, "error.common.internal_server_error", y recupera la
cadena de traducción correspondiente. También admite la sustitución de
variables, lo que permite insertar valores dinámicos en la traducción.

use serde_json;

pub fn t(&self, key: &str, variables: Option<HashMap<&str, &str>>) -> String {
    let parts: Vec<&str> = key.split('.').collect();
    let file_key = parts.get(0).unwrap_or(&"");
    let section_key = parts.get(1).unwrap_or(&"");
    let translation_keys = &parts[2..];

    if let Some(translation_module) = self.load_translation_module(file_key) {
        if let Some(section) = translation_module.get(*section_key) {
            let mut current_value: Option<&String> = None;

            for translation_key in translation_keys {
                if current_value.is_none() {
                    if let Some(next_value) = section.get(*translation_key) {
                        current_value = Some(next_value);
                    } else {
                        return format!("Key '{}' not found in '{}' locale", key, self.lang);
                    }
                }
            }

            if let Some(translation_string) = current_value {
                let mut translated_text = translation_string.clone();
                if let Some(variables) = variables {
                    for (variable, value) in variables {
                        let variable_format = format!("{{{}}}", variable);
                        translated_text = translated_text.replace(&variable_format, value);
                    }
                }
                translated_text
            } else {
                format!("Key '{}' not found in '{}' locale", key, self.lang)
            }
        } else {
            format!(
                "Section '{}' not found in '{}' locale",
                section_key, self.lang
            )
        }
    } else {
        format!("Module '{}' not found for '{}' locale", file_key, self.lang)
    }
}

Esta función hace lo siguiente:

Divide la clave en partes: file_key, section_key y la clave de traducción real.
Carga el archivo de traducción: Llama a load_translation_module para garantizar que se cargue el archivo correcto.
Recorre las claves: Navega a través del HashMap del archivo para encontrar la cadena de traducción deseada.
Maneja variables dinámicas: Si la traducción contiene variables como {username}, estas se reemplazan por los valores proporcionados en el mapa variables.

Por ejemplo, si la cadena de traducción es "{username}, Crea, Gana y Conéctate con OnlyCoiners!" y proporcionas {"username": "Rust"}, el resultado final será
"Rust, Crea, Gana y Conéctate con OnlyCoiners!".

Manejo de Errores

El sistema está diseñado para proporcionar mensajes de error útiles cuando
no se encuentran traducciones. Por ejemplo, si falta una sección o clave,
retorna un mensaje como:

Key 'error.common.INTERNAL_SERVER_ERROR' not found in 'en' locale

Esto garantiza que los desarrolladores puedan identificar fácilmente las
traducciones faltantes durante el desarrollo.

Ejemplos de uso en producción

El módulo de traducción se utiliza en producción en el OnlyCoiners API server.

Proporcionaremos algunos fragmentos de código que puedes usar como referencia.
Puedes comenzar creando un middleware como este para axum.

// #[derive(Clone)]
// pub struct Language(pub String);

use std::collections::HashSet;

use crate::{constants::language::{ALLOWED_LANGUAGE_LIST, EN}, schemas::language::Language};
use axum::{extract::Request, middleware::Next, response::Response};

pub async fn extract_client_language(
    mut request: Request, // mutable borrow for later modification
    next: Next,
) -> Result<Response, String> {
    let accept_language = {
        // Temporarily borrow the request immutably to get the header
        request
            .headers()
            .get("Accept-Language")
            .and_then(|value| value.to_str().ok())
            .unwrap_or("")
            .to_string() // convert to String to end the borrow
    };

    let mut locale = accept_language.split(',').next().unwrap_or(EN).to_string();
    // Remove any region specifier like en-US to en
    locale = locale.split('-').next().unwrap_or(EN).to_string();

    // Create a set of allowed languages for quick lookup
    let allowed_languages: HashSet<&str> = ALLOWED_LANGUAGE_LIST.iter().cloned().collect();

    // Verify if the extracted locale is allowed; if not, default to the default language
    if !allowed_languages.contains(locale.as_str()) {
        locale = EN.to_string();
    }

    // Insert the language into request extensions with mutable borrow
    request.extensions_mut().insert(Language(locale));

    // Proceed to the next middleware or handler
    let response = next.run(request).await;

    Ok(response)
}

Puedes incluir esto en tu aplicación axum.

let app = Router::new()
        .route("/", get(root))
        // Attach `/api` routes
        .nest("/bot", bot_routes)
        .nest("/admin", admin_routes)
        .nest("/api", api_routes)
        .layer(from_fn(extract_client_language))

A continuación, usa esto dentro de tu handler.

pub async fn find_user_list(
    Extension(session): Extension<SessionData>,
    Extension(language): Extension<Language>,
) -> Result<Json<Vec<UserListing>>, (StatusCode, Json<ErrorMessage>)> {
    let translator = Translator::new(&language.0);
    let not_authorized = translator.t("error.common.not_authorized", None);

    Err((
        StatusCode::UNAUTHORIZED,
        Json(ErrorMessage {
            text: not_authorized,
        }),
    ))
}

Opcionalmente, puedes crear pruebas para el módulo Translator y usar $cargo test para probarlo.

#[cfg(test)]
mod tests {
    use crate::translations::translator::Translator;

    use super::*;
    use std::collections::HashMap;

    #[test]
    fn test_translation_for_english_locale() {
        let translator = Translator::new("en");

        let translation = translator.t("error.common.internal_server_error", None);
        assert_eq!(translation, "Internal server error");

        let not_found = translator.t("error.common.non_existent", None);
        assert_eq!(not_found, "Key 'error.common.non_existent' not found in 'en' locale");
    }

    #[test]
    fn test_translation_for_portuguese_locale() {
        let translator = Translator::new("pt");

        // Test known translation
        let translation = translator.t("error.common.internal_server_error", None);
        println!("translation {}", translation);
        assert_eq!(translation, "Erro interno no servidor");

        // Test key not found
        let not_found = translator.t("error.common.non_existent", None);
        assert_eq!(not_found, "Key 'error.common.non_existent' not found in 'pt' locale");
    }

    #[test]
    fn test_translation_with_variables() {
        let translator = Translator::new("en");

        let mut variables = HashMap::new();
        variables.insert("resource", "User");

        let translation_with_vars = translator.t("error.common.not_found", Some(variables));
        assert_eq!(translation_with_vars, "User not found");
    }

    #[test]
    fn test_translation_module_not_found() {
        let translator = Translator::new("es");

        // Test loading a non-existent module
        let translation = translator.t("non_existent_module.common.internal_server_error", None);
        assert_eq!(
            translation,
            "Module 'non_existent_module' not found for 'es' locale"
        );
    }

    #[test]
    fn test_translation_section_not_found() {
        let translator = Translator::new("en");

        // Test section not found in translation file
        let translation = translator.t("error.non_existent_section.internal_server_error", None);
        assert_eq!(
            translation,
            "Section 'non_existent_section' not found in 'en' locale"
        );
    }
}

También puedes probar el middleware.

pub async fn test_handler(Extension(language): Extension<Language>) -> Json<serde_json::Value> {
    // Return a JSON response with the extracted language
    let response_message = match language.0.as_str() {
        "en" => "en",
        "pt" => "pt",
        "es" => "es",
        _ => "deafult",
    };

    Json(json!({ "message": response_message }))
}

#[cfg(test)]
mod tests {
    use crate::{
        constants::language::{EN, EN_US, ES, PT}, mdware::language::extract_client_language, tests::{test_handler, TRANSLATOR}  
    };
    use axum::{
        body::{to_bytes, Body}, http::Request, middleware::from_fn, Router
    };
    use hyper::StatusCode;
    use tower::ServiceExt; 
    use serde_json::{json, Value};

    #[tokio::test]
    async fn test_with_valid_accept_language_header() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        // Simulate a request with a valid Accept-Language header like
        let request = Request::builder()
            .header("Accept-Language", EN_US) // "en-US"
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();
        // println!("Response Body: {:?}", body_str);

        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": EN }));
    }

    #[tokio::test]
    async fn test_with_valid_accept_language_header_wiht_pt() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        let request = Request::builder()
            .header("Accept-Language", "pt")
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();

        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": PT }));
    }

    #[tokio::test]
    async fn test_with_valid_accept_language_header_wiht_pt_br() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        let request = Request::builder()
            .header("Accept-Language", "pt-BR")
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();

        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": PT }));
    }

    #[tokio::test]
    async fn test_with_valid_accept_language_header_wiht_es() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        let request = Request::builder()
            .header("Accept-Language", "es")
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();
        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": ES }));
    }

    #[tokio::test]
    async fn test_with_unsupported_language() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        let request = Request::builder()
            .header("Accept-Language", "fr")
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();

        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": EN }));
    }

    #[tokio::test]
    async fn test_without_accept_language_header() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        let request = Request::builder()
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();

        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": EN }));
    }
}

Puedes usar estos archivos de traducción JSON como referencia.

en.json
{
  "common": {
    "internal_server_error": "Internal server error",
    "not_authorized": "You are not authorized to use this resource",
    "not_found": "{resource} not found"
  },
}
pt.json
{
  "common": {
    "internal_server_error": "Erro interno no servidor",
    "not_authorized": "Você não está autorizado a usar este recurso",
    "not_found": "{resource} não encontrado"
  },
}
es.json
{
  "common": {
    "internal_server_error": "Error interno del servidor",
    "not_authorized": "No estás autorizado para usar este recurso",
    "not_found": "{resource} no encontrado"
  },
}

Conclusión

Este sistema de traducción maneja eficientemente las traducciones en una
aplicación Rust, utilizando almacenamiento estático y acceso seguro para
hilos. Al aprovechar OnceCell y Mutex, podemos garantizar que los archivos
de traducción se carguen una vez y se almacenen en caché, mejorando el
rendimiento y reduciendo el acceso al disco. La función t permite la
recuperación flexible de traducciones con soporte para variables dinámicas,
lo que la convierte en una herramienta poderosa para la localización.

Si estás construyendo una aplicación que requiere localización, este
enfoque ofrece una solución simple, escalable y eficiente para la gestión de
traducciones. Al utilizar las características de seguridad de memoria de Rust,
garantizas que tus traducciones se manejen de manera segura y eficiente en
múltiples hilos.

Esperamos que este post te haya ayudado a implementar un sistema simple de
traducción utilizando Rust. Utilizamos Rust activamente en producción y estamos
buscando contratar más desarrolladores de Rust.

Sientete libre de unirte a nuestra plataforma si te gustó este post y
apoya a una empresa que utiliza Rust en producción!

Maneira simples de adicionar suporte a i18n no Rust com exemplos e testes

OnlyCoiners — Fri, 25 Oct 2024 10:30:50 +0000

A localização é crucial para o desenvolvimento de software moderno. Ao
suportar múltiplos idiomas, os aplicativos podem alcançar um público mais
amplo e se tornar mais inclusivos, alinhando-se com a missão do OnlyCoiners.

No entanto, gerenciar traduções de forma eficiente em um ambiente
multi-thread pode ser desafiador. Neste post, exploraremos como aproveitar o
OnceCell e o Mutex do Rust para lidar com traduções armazenadas em arquivos
JSON, armazenando-as em memória para facilitar a localização eficaz em todo
o aplicativo.

Você pode estar curioso por que escolhemos não usar uma solução estabelecida
como rust-i18n. Queríamos criar uma versão equivalente ao snippet de código
Python implementado no nosso servidor FastAPI, conforme descrito
neste post,
para reutilizar arquivos de tradução e facilitar o processo de reescrever
parte do código Python no nosso servidor em Rust OnlyCoiners API server.

Você pode testá-lo em produção aqui.

Você pode criar um token de API aqui primeiro
depois de criar uma conta no OnlyCoiners.

Se sua empresa está procurando contratar um desenvolvedor Rust ou fornecer
suporte a outra organização que usa Rust em produção, considere postar uma
vaga no OnlyCoiners.

Encontre e poste vagas de Rust no nosso quadro de empregos.

Entre em contato para dúvidas, e teremos o prazer
de oferecer a você e sua empresa descontos exclusivos e outros benefícios se tá contratando e quer ter uma parceria com nossa empresa!

Sinta-se à vontade para se juntar à nossa plataforma se você for um Rustacean
todos vocês são bem-vindos e também contratamos!

Pode ler versão EN ou ES se quiser.

Pode ver postagem original em nosso site também.

Trecho Completo de Código para translator.rs

Antes de prosseguirmos, gostaríamos de apresentar o trecho completo de
código em Rust para a struct Translator, projetado para facilitar a
internacionalização dentro da sua base de código Rust.

use once_cell::sync::OnceCell;
use serde_json;
use std::collections::HashMap;
use std::sync::Mutex;
use std::{env, fs};

// 1. Global static storage for translation modules
static TRANSLATIONS: OnceCell<Mutex<HashMap<String, HashMap<String, HashMap<String, String>>>>> =
    OnceCell::new();

pub struct Translator {
    lang: String,
}

impl Translator {
    // 2. Initialize the translator with a language
    pub fn new(lang: &str) -> Self {
        // Ensure translations are loaded once
        let _ = TRANSLATIONS.get_or_init(|| Mutex::new(HashMap::new()));
        Translator {
            lang: lang.to_string(),
        }
    }

    // 3. Load translations from files or other sources
    fn load_translation_module(
        &self,
        file_key: &str,
    ) -> Option<HashMap<String, HashMap<String, String>>> {
        let mut translations = TRANSLATIONS.get().unwrap().lock().unwrap();

        // Get the current working directory and construct the full path dynamically
        let current_dir = env::current_dir().unwrap();
        let module_path =
            current_dir.join(format!("src/translations/{}/{}.json", self.lang, file_key));

        // If translation is already loaded, return a cloned version
        if let Some(file_translations) = translations.get(file_key) {
            return Some(file_translations.clone());
        }

        // Load the translation file - error.json
        match fs::read_to_string(module_path) {
            Ok(content) => {
                // Parse the JSON into a nested HashMap - error -> common -> internal_server_error
                let file_translations: HashMap<String, HashMap<String, String>> =
                    serde_json::from_str(&content).unwrap_or_default();

                translations.insert(file_key.to_string(), file_translations.clone());
                Some(file_translations)
            }
            Err(e) => {
                tracing::error!("Error loading translation file - {}", e);
                None
            }
        }
    }

    // 4. Translate based on key and optional variables
    pub fn t(&self, key: &str, variables: Option<HashMap<&str, &str>>) -> String {
        let parts: Vec<&str> = key.split('.').collect();
        let file_key = parts.get(0).unwrap_or(&""); // "error"
        let section_key = parts.get(1).unwrap_or(&""); // "common"
        let translation_keys = &parts[2..]; // "INTERNAL_SERVER_ERROR"

        // Load the correct translation module (e.g., "error.json")
        if let Some(translation_module) = self.load_translation_module(file_key) {
            if let Some(section) = translation_module.get(*section_key) {
                let mut current_value: Option<&String> = None;

                // Traverse the translation keys to get the final string value
                for translation_key in translation_keys {
                    if current_value.is_none() {
                        // At the beginning, current_value is None, so we access the section (a HashMap)
                        if let Some(next_value) = section.get(*translation_key) {
                            current_value = Some(next_value);
                        } else {
                            return format!("Key '{}' not found in '{}' locale", key, self.lang);
                        }
                    }
                }

                // At this point, current_value should be a &String
                if let Some(translation_string) = current_value {
                    let mut translated_text = translation_string.clone();

                    // Handle variables if present
                    if let Some(variables) = variables {
                        for (variable, value) in variables {
                            let variable_format = format!("{{{}}}", variable);
                            translated_text = translated_text.replace(&variable_format, value);
                        }
                    }
                    translated_text
                } else {
                    format!("Key '{}' not found in '{}' locale", key, self.lang)
                }
            } else {
                format!(
                    "Section '{}' not found in '{}' locale",
                    section_key, self.lang
                )
            }
        } else {
            format!("Module '{}' not found for '{}' locale", file_key, self.lang)
        }
    }
}

Por que Usar Armazenamento Estático para Traduções?

Ao trabalhar em aplicativos multi-thread, lidar com dados globais requer
atenção cuidadosa. Sem a sincronização adequada, você pode enfrentar
condições de corrida, falhas ou outros problemas. O Rust oferece ferramentas
como OnceCell e Mutex para resolver esses problemas de forma segura.

OnceCell garante que um valor seja inicializado apenas uma vez e
fornece acesso a ele entre as threads. Mutex garante acesso seguro e
mutável a dados compartilhados entre threads, bloqueando o acesso quando uma
thread está lendo ou escrevendo.

Ao combinar esses dois, podemos criar um armazenamento global estático que
armazena em cache arquivos de tradução em memória, para que sejam carregados
uma vez e reutilizados durante toda a vida útil do programa. Esta abordagem
evita o carregamento repetido de arquivos do disco e garante que as traduções
sejam tratadas de forma segura em um ambiente concorrente.

Explicação do Código

Vamos mergulhar no código que alimenta este sistema de tradução. Ele utiliza
uma combinação de OnceCell, Mutex e um HashMap aninhado para carregar
e armazenar traduções de arquivos JSON. Uma vez que um arquivo é carregado,
ele é armazenado em memória e reutilizado para solicitações subsequentes.

1. Armazenamento Global de Traduções

Os dados de tradução são armazenados em uma variável estática global,
TRANSLATIONS, que usa OnceCell e Mutex para garantir que os dados
sejam thread-safe e inicializados apenas uma vez. A estrutura do HashMap
permite organizar traduções de forma hierárquica.

O primeiro nível armazena traduções por chave de arquivo como error.json.
O segundo nível agrupa traduções por chave de seção, como common.
O terceiro nível armazena os pares chave-valor da tradução real.

use once_cell::sync::OnceCell;
use std::collections::HashMap;
use std::sync::Mutex;

static TRANSLATIONS: OnceCell<Mutex<HashMap<String, HashMap<String, HashMap<String, String>>>>> =
    OnceCell::new();

Aqui está como o HashMap aninhado funciona

Chave de arquivo, como "error", aponta para um mapa de chaves de seção.
Cada chave de seção, como "common", contém as strings de tradução, organizadas por chaves como "internal_server_error", com mensagens correspondentes, como "Erro interno no servidor", conforme você pode ver no arquivo JSON usado em produção no servidor da API OnlyCoiners.

src/translations/en/error.json

{
  "common": {
    "internal_server_error": "Internal server error",
    "not_authorized": "You are not authorized to use this resource",
    "not_found": "{resource} not found"
  },
  "token": {
    "no_api_user_token": "API-USER-TOKEN header is not included",
    "invalid_api_user_token": "API-USER-TOKEN header is not valid",
    "no_api_admin_token": "API-ADMIN-TOKEN header is not included",
    "unable_to_read_api_token": "Unable to read API Token"
  },
  "database": {
    "unable_to_query_database": "Unable to query database"
  }
}

2. Inicializando o Translator

A struct Translator representa um objeto vinculado a um idioma específico,
como "en" para Inglês ou "pt" para Português. Quando criamos uma instância
de Translator, a variável global TRANSLATIONS é inicializada, caso ainda
não tenha sido.

pub struct Translator {
    lang: String,
}

impl Translator {
    pub fn new(lang: &str) -> Self {
        let _ = TRANSLATIONS.get_or_init(|| Mutex::new(HashMap::new()));
        Translator {
            lang: lang.to_string(),
        }
    }
}

Isso garante que o armazenamento global para traduções esteja configurado e
pronto para ser utilizado. O campo lang na struct Translator armazena o
código do idioma, como "en" para Inglês ou "es" para Espanhol, e é usado
ao carregar arquivos de tradução.

3. Carregando Arquivos de Tradução

A função load_translation_module é responsável por carregar os dados de
tradução de um arquivo, como src/translations/en/error.json. Ela lê o
arquivo JSON, faz o parsing dos dados e os armazena no mapa global
TRANSLATIONS para uso futuro. Se o arquivo já foi carregado, ela simplesmente
retorna a versão armazenada em cache.

use std::{env, fs};

fn load_translation_module(
    &self,
    file_key: &str,
) -> Option<HashMap<String, HashMap<String, String>>> {
    let mut translations = TRANSLATIONS.get().unwrap().lock().unwrap();
    let current_dir = env::current_dir().unwrap();
    let module_path =
        current_dir.join(format!("src/translations/{}/{}.json", self.lang, file_key));

    if let Some(file_translations) = translations.get(file_key) {
        return Some(file_translations.clone());
    }

    match fs::read_to_string(module_path) {
        Ok(content) => {
            let file_translations: HashMap<String, HashMap<String, String>> =
                serde_json::from_str(&content).unwrap_or_default();
            translations.insert(file_key.to_string(), file_translations.clone());
            Some(file_translations)
        }
        Err(e) => {
            tracing::error!("Error loading translation file - {}", e);
            None
        }
    }
}

Esta função faz o seguinte:

Verifica se o arquivo já está carregado: Se estiver, ela retorna os dados armazenados em cache no mapa TRANSLATIONS.
Carrega o arquivo de tradução: Se o arquivo ainda não foi carregado, ela lê o arquivo JSON no caminho src/translations/{lang}/{file}.json, faz o parsing do conteúdo em um HashMap e o armazena em memória.
Lida com erros: Se o arquivo não puder ser lido, por exemplo, se não existir, uma mensagem de erro é registrada, e a função retorna None.

4. Traduzindo Chaves com Variáveis

Uma vez que as traduções estão carregadas, você pode recuperá-las usando a
função t. Esta função recebe uma chave, que é uma string separada por
pontos. Por exemplo, "error.common.internal_server_error", e recupera a
string de tradução correspondente. Ela também suporta a substituição de
variáveis, permitindo inserir valores dinâmicos na tradução.

use serde_json;

pub fn t(&self, key: &str, variables: Option<HashMap<&str, &str>>) -> String {
    let parts: Vec<&str> = key.split('.').collect();
    let file_key = parts.get(0).unwrap_or(&"");
    let section_key = parts.get(1).unwrap_or(&"");
    let translation_keys = &parts[2..];

    if let Some(translation_module) = self.load_translation_module(file_key) {
        if let Some(section) = translation_module.get(*section_key) {
            let mut current_value: Option<&String> = None;

            for translation_key in translation_keys {
                if current_value.is_none() {
                    if let Some(next_value) = section.get(*translation_key) {
                        current_value = Some(next_value);
                    } else {
                        return format!("Key '{}' not found in '{}' locale", key, self.lang);
                    }
                }
            }

            if let Some(translation_string) = current_value {
                let mut translated_text = translation_string.clone();
                if let Some(variables) = variables {
                    for (variable, value) in variables {
                        let variable_format = format!("{{{}}}", variable);
                        translated_text = translated_text.replace(&variable_format, value);
                    }
                }
                translated_text
            } else {
                format!("Key '{}' not found in '{}' locale", key, self.lang)
            }
        } else {
            format!(
                "Section '{}' not found in '{}' locale",
                section_key, self.lang
            )
        }
    } else {
        format!("Module '{}' not found for '{}' locale", file_key, self.lang)
    }
}

Esta função faz o seguinte:

Divide a chave em partes: file_key, section_key e a chave de tradução real.
Carrega o arquivo de tradução: Ela chama load_translation_module para garantir que o arquivo correto seja carregado.
Percorre as chaves: Navega pelo HashMap do arquivo para encontrar a string de tradução desejada.
Lida com variáveis dinâmicas: Se a tradução contém variáveis como {username}, elas são substituídas pelos valores passados no mapa variables.

Por exemplo, se a string de tradução for "{username}, Crie, Ganhe e Conecte-se com OnlyCoiners!" e você fornecer {"username": "Rust"}, o resultado final será
"Rust, Crie, Ganhe e Conecte-se com OnlyCoiners!".

Tratamento de Erros

O sistema foi projetado para fornecer mensagens de erro úteis quando
traduções não são encontradas. Por exemplo, se uma seção ou chave estiver
faltando, ele retorna uma mensagem como:

Key 'error.common.INTERNAL_SERVER_ERROR' not found in 'en' locale

Isso garante que os desenvolvedores possam identificar facilmente traduções ausentes durante o desenvolvimento.

Exemplos de uso em produção

O módulo de tradução é utilizado em produção no OnlyCoiners API server.

Vamos fornecer alguns trechos de código que você pode usar como referência.
Você pode primeiro criar um middleware como este para o axum.

// #[derive(Clone)]
// pub struct Language(pub String);

use std::collections::HashSet;

use crate::{constants::language::{ALLOWED_LANGUAGE_LIST, EN}, schemas::language::Language};
use axum::{extract::Request, middleware::Next, response::Response};

pub async fn extract_client_language(
    mut request: Request, // mutable borrow for later modification
    next: Next,
) -> Result<Response, String> {
    let accept_language = {
        // Temporarily borrow the request immutably to get the header
        request
            .headers()
            .get("Accept-Language")
            .and_then(|value| value.to_str().ok())
            .unwrap_or("")
            .to_string() // convert to String to end the borrow
    };

    let mut locale = accept_language.split(',').next().unwrap_or(EN).to_string();
    // Remove any region specifier like en-US to en
    locale = locale.split('-').next().unwrap_or(EN).to_string();

    // Create a set of allowed languages for quick lookup
    let allowed_languages: HashSet<&str> = ALLOWED_LANGUAGE_LIST.iter().cloned().collect();

    // Verify if the extracted locale is allowed; if not, default to the default language
    if !allowed_languages.contains(locale.as_str()) {
        locale = EN.to_string();
    }

    // Insert the language into request extensions with mutable borrow
    request.extensions_mut().insert(Language(locale));

    // Proceed to the next middleware or handler
    let response = next.run(request).await;

    Ok(response)
}

Você pode incluir isso no seu aplicativo axum.

let app = Router::new()
        .route("/", get(root))
        // Attach `/api` routes
        .nest("/bot", bot_routes)
        .nest("/admin", admin_routes)
        .nest("/api", api_routes)
        .layer(from_fn(extract_client_language))

Em seguida, use isso dentro do seu handler.

pub async fn find_user_list(
    Extension(session): Extension<SessionData>,
    Extension(language): Extension<Language>,
) -> Result<Json<Vec<UserListing>>, (StatusCode, Json<ErrorMessage>)> {
    let translator = Translator::new(&language.0);
    let not_authorized = translator.t("error.common.not_authorized", None);

    Err((
        StatusCode::UNAUTHORIZED,
        Json(ErrorMessage {
            text: not_authorized,
        }),
    ))
}

Opcionalmente, você pode criar testes para o módulo Translator e usar $cargo test para testá-lo.

#[cfg(test)]
mod tests {
    use crate::translations::translator::Translator;

    use super::*;
    use std::collections::HashMap;

    #[test]
    fn test_translation_for_english_locale() {
        let translator = Translator::new("en");

        let translation = translator.t("error.common.internal_server_error", None);
        assert_eq!(translation, "Internal server error");

        let not_found = translator.t("error.common.non_existent", None);
        assert_eq!(not_found, "Key 'error.common.non_existent' not found in 'en' locale");
    }

    #[test]
    fn test_translation_for_portuguese_locale() {
        let translator = Translator::new("pt");

        // Test known translation
        let translation = translator.t("error.common.internal_server_error", None);
        println!("translation {}", translation);
        assert_eq!(translation, "Erro interno no servidor");

        // Test key not found
        let not_found = translator.t("error.common.non_existent", None);
        assert_eq!(not_found, "Key 'error.common.non_existent' not found in 'pt' locale");
    }

    #[test]
    fn test_translation_with_variables() {
        let translator = Translator::new("en");

        let mut variables = HashMap::new();
        variables.insert("resource", "User");

        let translation_with_vars = translator.t("error.common.not_found", Some(variables));
        assert_eq!(translation_with_vars, "User not found");
    }

    #[test]
    fn test_translation_module_not_found() {
        let translator = Translator::new("es");

        // Test loading a non-existent module
        let translation = translator.t("non_existent_module.common.internal_server_error", None);
        assert_eq!(
            translation,
            "Module 'non_existent_module' not found for 'es' locale"
        );
    }

    #[test]
    fn test_translation_section_not_found() {
        let translator = Translator::new("en");

        // Test section not found in translation file
        let translation = translator.t("error.non_existent_section.internal_server_error", None);
        assert_eq!(
            translation,
            "Section 'non_existent_section' not found in 'en' locale"
        );
    }
}

Você também pode testar o middleware.

pub async fn test_handler(Extension(language): Extension<Language>) -> Json<serde_json::Value> {
    // Return a JSON response with the extracted language
    let response_message = match language.0.as_str() {
        "en" => "en",
        "pt" => "pt",
        "es" => "es",
        _ => "deafult",
    };

    Json(json!({ "message": response_message }))
}

#[cfg(test)]
mod tests {
    use crate::{
        constants::language::{EN, EN_US, ES, PT}, mdware::language::extract_client_language, tests::{test_handler, TRANSLATOR}  
    };
    use axum::{
        body::{to_bytes, Body}, http::Request, middleware::from_fn, Router
    };
    use hyper::StatusCode;
    use tower::ServiceExt; 
    use serde_json::{json, Value};

    #[tokio::test]
    async fn test_with_valid_accept_language_header() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        // Simulate a request with a valid Accept-Language header like
        let request = Request::builder()
            .header("Accept-Language", EN_US) // "en-US"
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();
        // println!("Response Body: {:?}", body_str);

        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": EN }));
    }

    #[tokio::test]
    async fn test_with_valid_accept_language_header_wiht_pt() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        let request = Request::builder()
            .header("Accept-Language", "pt")
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();

        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": PT }));
    }

    #[tokio::test]
    async fn test_with_valid_accept_language_header_wiht_pt_br() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        let request = Request::builder()
            .header("Accept-Language", "pt-BR")
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();

        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": PT }));
    }

    #[tokio::test]
    async fn test_with_valid_accept_language_header_wiht_es() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        let request = Request::builder()
            .header("Accept-Language", "es")
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();
        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": ES }));
    }

    #[tokio::test]
    async fn test_with_unsupported_language() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        let request = Request::builder()
            .header("Accept-Language", "fr")
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();

        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": EN }));
    }

    #[tokio::test]
    async fn test_without_accept_language_header() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        let request = Request::builder()
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();

        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": EN }));
    }
}

Você pode usar esses arquivos de tradução JSON como referência.

en.json
{
  "common": {
    "internal_server_error": "Internal server error",
    "not_authorized": "You are not authorized to use this resource",
    "not_found": "{resource} not found"
  },
}
pt.json
{
  "common": {
    "internal_server_error": "Erro interno no servidor",
    "not_authorized": "Você não está autorizado a usar este recurso",
    "not_found": "{resource} não encontrado"
  },
}
es.json
{
  "common": {
    "internal_server_error": "Error interno del servidor",
    "not_authorized": "No estás autorizado para usar este recurso",
    "not_found": "{resource} no encontrado"
  },
}

Conclusão

Este sistema de tradução lida de forma eficiente com traduções em uma
aplicação Rust, utilizando armazenamento estático e acesso thread-safe.
Ao aproveitar OnceCell e Mutex, podemos garantir que os arquivos de
tradução sejam carregados uma vez e armazenados em cache, melhorando o
desempenho e reduzindo o acesso ao disco. A função t permite a
recuperação flexível de traduções com suporte para variáveis dinâmicas,
tornando-a uma ferramenta poderosa para a localização.

Se você está construindo um aplicativo que requer localização, essa
abordagem oferece uma solução simples, escalável e eficiente para o
gerenciamento de traduções. Ao usar os recursos de segurança de memória
do Rust, você garante que suas traduções sejam tratadas com segurança e
eficiência em múltiplas threads.

Esperamos que este post tenha ajudado você a implementar um sistema simples
de tradução utilizando Rust. Usamos Rust ativamente em produção e estamos
procurando contratar mais desenvolvedores Rust.

Sinta-se à vontade para se juntar à nossa plataforma se gostou deste post e
apoie uma empresa que usa Rust em produção!

Simple way to make i18n support in Rust with with examples and tests

OnlyCoiners — Fri, 25 Oct 2024 10:26:35 +0000

Localization is crucial for modern software development. By supporting multiple languages, applications can reach a wider audience and become more inclusive, aligning with OnlyCoiners' mission.

However, managing translations efficiently in a multi-threaded environment can be challenging. In this post, we'll explore how to leverage Rust's OnceCell and Mutex to handle translations stored in JSON files, caching them in memory to facilitate effective localization throughout the application.

You might be curious why we chose not to use an established solution like rust-i18n. What we want was to create a version equivalent to the Python code snippet implemented in our FastAPI server, as described in this post so we can reuse translation files and ease the process of rewriting some Python code in our Rust OnlyCoiners API server.

You can test it working here in production.

You can create an API token here first after you make an account at OnlyCoiners.

If your company is looking to hire a Rust developer or provide support to another organization using Rust in production, consider posting a job at OnlyCoiners.

Find and post Rust jobs at our job board.

Contact us for inquiries, and we’ll be happy to offer you and your company exclusive discounts and other benefits if you are hiring or want to have a partnership with us!

Feel free to join our platform if you are a Rustacean and we welcome all of you and hire as well!

You can see the version ES ou PT also.

You can see the original post at our website.

This week in Rust team, if you share this post, please use the original post as a way to support a company use Rust in production.

Complete Code Snippet for translator.rs

Before we proceed, we like to present the complete Rust code snippet for the Translator struct, designed to facilitate internationalization within your Rust codebase.

use once_cell::sync::OnceCell;
use serde_json;
use std::collections::HashMap;
use std::sync::Mutex;
use std::{env, fs};

// 1. Global static storage for translation modules
static TRANSLATIONS: OnceCell<Mutex<HashMap<String, HashMap<String, HashMap<String, String>>>>> =
    OnceCell::new();

pub struct Translator {
    lang: String,
}

impl Translator {
    // 2. Initialize the translator with a language
    pub fn new(lang: &str) -> Self {
        // Ensure translations are loaded once
        let _ = TRANSLATIONS.get_or_init(|| Mutex::new(HashMap::new()));
        Translator {
            lang: lang.to_string(),
        }
    }

    // 3. Load translations from files or other sources
    fn load_translation_module(
        &self,
        file_key: &str,
    ) -> Option<HashMap<String, HashMap<String, String>>> {
        let mut translations = TRANSLATIONS.get().unwrap().lock().unwrap();

        // Get the current working directory and construct the full path dynamically
        let current_dir = env::current_dir().unwrap();
        let module_path =
            current_dir.join(format!("src/translations/{}/{}.json", self.lang, file_key));

        // If translation is already loaded, return a cloned version
        if let Some(file_translations) = translations.get(file_key) {
            return Some(file_translations.clone());
        }

        // Load the translation file - error.json
        match fs::read_to_string(module_path) {
            Ok(content) => {
                // Parse the JSON into a nested HashMap - error -> common -> internal_server_error
                let file_translations: HashMap<String, HashMap<String, String>> =
                    serde_json::from_str(&content).unwrap_or_default();

                translations.insert(file_key.to_string(), file_translations.clone());
                Some(file_translations)
            }
            Err(e) => {
                tracing::error!("Error loading translation file - {}", e);
                None
            }
        }
    }

    // 4. Translate based on key and optional variables
    pub fn t(&self, key: &str, variables: Option<HashMap<&str, &str>>) -> String {
        let parts: Vec<&str> = key.split('.').collect();
        let file_key = parts.get(0).unwrap_or(&""); // "error"
        let section_key = parts.get(1).unwrap_or(&""); // "common"
        let translation_keys = &parts[2..]; // "INTERNAL_SERVER_ERROR"

        // Load the correct translation module (e.g., "error.json")
        if let Some(translation_module) = self.load_translation_module(file_key) {
            if let Some(section) = translation_module.get(*section_key) {
                let mut current_value: Option<&String> = None;

                // Traverse the translation keys to get the final string value
                for translation_key in translation_keys {
                    if current_value.is_none() {
                        // At the beginning, current_value is None, so we access the section (a HashMap)
                        if let Some(next_value) = section.get(*translation_key) {
                            current_value = Some(next_value);
                        } else {
                            return format!("Key '{}' not found in '{}' locale", key, self.lang);
                        }
                    }
                }

                // At this point, current_value should be a &String
                if let Some(translation_string) = current_value {
                    let mut translated_text = translation_string.clone();

                    // Handle variables if present
                    if let Some(variables) = variables {
                        for (variable, value) in variables {
                            let variable_format = format!("{{{}}}", variable);
                            translated_text = translated_text.replace(&variable_format, value);
                        }
                    }
                    translated_text
                } else {
                    format!("Key '{}' not found in '{}' locale", key, self.lang)
                }
            } else {
                format!(
                    "Section '{}' not found in '{}' locale",
                    section_key, self.lang
                )
            }
        } else {
            format!("Module '{}' not found for '{}' locale", file_key, self.lang)
        }
    }
}

Why Use Static Storage for Translations?

When working on multi-threaded applications, handling global data requires careful thought. Without proper synchronization, you may encounter data races, crashes, or other issues. Rust provides tools like OnceCell and Mutex to solve these problems safely.

OnceCell ensures that a value is initialized only once and provides access to it across threads. Mutex guarantees safe, mutable access to shared data between threads by locking access when one thread is reading or writing.

By combining these two, we can create a static global storage that caches translation files in memory, so they are loaded once and then reused throughout the lifetime of the program. This approach avoids repeatedly loading files from disk and ensures translations are handled safely in a concurrent environment.

The Code Walkthrough

Let’s dive into the code that powers this translation system. It leverages a combination of OnceCell, Mutex, and a nested HashMap to load and store translations from JSON files. Once a file is loaded, it’s cached in memory and reused for subsequent requests.

1. Global Translation Storage

The translation data is stored in a global static variable, TRANSLATIONS, which uses OnceCell and Mutex to ensure the data is thread-safe and only initialized once. The structure of the HashMap allows for organizing translations in a hierarchical way:

The first level stores translations by file key like error.json.
The second level groups translations by section key like common.
The third level stores the actual translation key-value pairs.

use once_cell::sync::OnceCell;
use std::collections::HashMap;
use std::sync::Mutex;

static TRANSLATIONS: OnceCell<Mutex<HashMap<String, HashMap<String, HashMap<String, String>>>>> =
    OnceCell::new();

Here’s how the nested HashMap works:

File key like "error" points to a map of section keys.
Each section key like "common" contains the translation strings, organized by keys like "internal_server_error", with corresponding messages like "Internal server error" as you can see below in json file used in production for OnlyCoiners API server.

src/translations/en/error.json

{
  "common": {
    "internal_server_error": "Internal server error",
    "not_authorized": "You are not authorized to use this resource",
    "not_found": "{resource} not found"
  },
  "token": {
    "no_api_user_token": "API-USER-TOKEN header is not included",
    "invalid_api_user_token": "API-USER-TOKEN header is not valid",
    "no_api_admin_token": "API-ADMIN-TOKEN header is not included",
    "unable_to_read_api_token": "Unable to read API Token"
  },
  "database": {
    "unable_to_query_database": "Unable to query database"
  }
}

2. Initializing the Translator

The Translator struct represents an object that is tied to a specific language like "en" for English or "pt" for Portuguese. When we create a Translator instance, the TRANSLATIONS global variable is initialized if it hasn’t been already.

pub struct Translator {
    lang: String,
}

impl Translator {
    pub fn new(lang: &str) -> Self {
        let _ = TRANSLATIONS.get_or_init(|| Mutex::new(HashMap::new()));
        Translator {
            lang: lang.to_string(),
        }
    }
}

This ensures that the global storage for translations is set up and ready to be used. The lang field in the Translator struct stores the language code, such as "en" for English or "es" for Spanish, and is used when loading translation files.

3. Loading Translation Files

The load_translation_module function is responsible for loading translation data from a file like src/translations/en/error.json. It reads the JSON file, parses it, and stores the data in the global TRANSLATIONS map for future use. If the file has already been loaded, it simply returns the cached version.

use std::{env, fs};

fn load_translation_module(
    &self,
    file_key: &str,
) -> Option<HashMap<String, HashMap<String, String>>> {
    let mut translations = TRANSLATIONS.get().unwrap().lock().unwrap();
    let current_dir = env::current_dir().unwrap();
    let module_path =
        current_dir.join(format!("src/translations/{}/{}.json", self.lang, file_key));

    if let Some(file_translations) = translations.get(file_key) {
        return Some(file_translations.clone());
    }

    match fs::read_to_string(module_path) {
        Ok(content) => {
            let file_translations: HashMap<String, HashMap<String, String>> =
                serde_json::from_str(&content).unwrap_or_default();
            translations.insert(file_key.to_string(), file_translations.clone());
            Some(file_translations)
        }
        Err(e) => {
            tracing::error!("Error loading translation file - {}", e);
            None
        }
    }
}

This function does the following.

Check if the file is already loaded: If it is, it returns the cached data from the TRANSLATIONS map.
Load the translation file: If the file hasn’t been loaded yet, it reads the JSON file from the src/translations/{lang}/{file}.json path, parses the content into a HashMap, and stores it in memory.
Handle errors: If the file cannot be read for exmaple, if it doesn’t exist, an error message is logged, and the function returns None.

4. Translating Keys with Variables

Once the translations are loaded, you can retrieve them using the t function. This function takes a key, which is a dot-separated string. For example, "error.common.internal_server_error", and retrieves the corresponding translation string. It also supports variable replacement, allowing you to insert dynamic values into the translation.

use serde_json;

pub fn t(&self, key: &str, variables: Option<HashMap<&str, &str>>) -> String {
    let parts: Vec<&str> = key.split('.').collect();
    let file_key = parts.get(0).unwrap_or(&"");
    let section_key = parts.get(1).unwrap_or(&"");
    let translation_keys = &parts[2..];

    if let Some(translation_module) = self.load_translation_module(file_key) {
        if let Some(section) = translation_module.get(*section_key) {
            let mut current_value: Option<&String> = None;

            for translation_key in translation_keys {
                if current_value.is_none() {
                    if let Some(next_value) = section.get(*translation_key) {
                        current_value = Some(next_value);
                    } else {
                        return format!("Key '{}' not found in '{}' locale", key, self.lang);
                    }
                }
            }

            if let Some(translation_string) = current_value {
                let mut translated_text = translation_string.clone();
                if let Some(variables) = variables {
                    for (variable, value) in variables {
                        let variable_format = format!("{{{}}}", variable);
                        translated_text = translated_text.replace(&variable_format, value);
                    }
                }
                translated_text
            } else {
                format!("Key '{}' not found in '{}' locale", key, self.lang)
            }
        } else {
            format!(
                "Section '{}' not found in '{}' locale",
                section_key, self.lang
            )
        }
    } else {
        format!("Module '{}' not found for '{}' locale", file_key, self.lang)
    }
}

This function does these.

Splits the key into parts: file_key, section_key, and the actual translation key(s).
Loads the translation file: It calls load_translation_module to ensure that the correct file is loaded.
Traverses the keys: It navigates through the file’s HashMap to find the desired translation string.
Handles dynamic variables: If the translation contains placeholders like {username}, they are replaced with the values passed in the variables map.

For example, if the translation string is "{username}, Create, Earn and Network with OnlyCoiners!" and you provide {"username": "Rust"}, the final result will be "Rust, Create, Earn and Network with OnlyCoiners!".

Error Handling

The system is designed to provide useful error messages when translations cannot be found. For instance, if a section or key is missing, it returns a message like:

Key 'error.common.INTERNAL_SERVER_ERROR' not found in 'en' locale

This ensures that developers can easily spot missing translations during development.

Usage examples in production

The translator module is used in production at OnlyCoiners API server.

We will give you a few code snippets you can use as a reference. You can first make a mdware like this for axum.

// #[derive(Clone)]
// pub struct Language(pub String);

use std::collections::HashSet;

use crate::{constants::language::{ALLOWED_LANGUAGE_LIST, EN}, schemas::language::Language};
use axum::{extract::Request, middleware::Next, response::Response};

pub async fn extract_client_language(
    mut request: Request, // mutable borrow for later modification
    next: Next,
) -> Result<Response, String> {
    let accept_language = {
        // Temporarily borrow the request immutably to get the header
        request
            .headers()
            .get("Accept-Language")
            .and_then(|value| value.to_str().ok())
            .unwrap_or("")
            .to_string() // convert to String to end the borrow
    };

    let mut locale = accept_language.split(',').next().unwrap_or(EN).to_string();
    // Remove any region specifier like en-US to en
    locale = locale.split('-').next().unwrap_or(EN).to_string();

    // Create a set of allowed languages for quick lookup
    let allowed_languages: HashSet<&str> = ALLOWED_LANGUAGE_LIST.iter().cloned().collect();

    // Verify if the extracted locale is allowed; if not, default to the default language
    if !allowed_languages.contains(locale.as_str()) {
        locale = EN.to_string();
    }

    // Insert the language into request extensions with mutable borrow
    request.extensions_mut().insert(Language(locale));

    // Proceed to the next middleware or handler
    let response = next.run(request).await;

    Ok(response)
}

You can include that to your axum app.

let app = Router::new()
        .route("/", get(root))
        // Attach `/api` routes
        .nest("/bot", bot_routes)
        .nest("/admin", admin_routes)
        .nest("/api", api_routes)
        .layer(from_fn(extract_client_language))

Then, use it inside your handler.

pub async fn find_user_list(
    Extension(session): Extension<SessionData>,
    Extension(language): Extension<Language>,
) -> Result<Json<Vec<UserListing>>, (StatusCode, Json<ErrorMessage>)> {
    let translator = Translator::new(&language.0);
    let not_authorized = translator.t("error.common.not_authorized", None);

    Err((
        StatusCode::UNAUTHORIZED,
        Json(ErrorMessage {
            text: not_authorized,
        }),
    ))
}

Optionally, you can make tests for Translator module and use $cargo test to test.

#[cfg(test)]
mod tests {
    use crate::translations::translator::Translator;

    use super::*;
    use std::collections::HashMap;

    #[test]
    fn test_translation_for_english_locale() {
        let translator = Translator::new("en");

        let translation = translator.t("error.common.internal_server_error", None);
        assert_eq!(translation, "Internal server error");

        let not_found = translator.t("error.common.non_existent", None);
        assert_eq!(not_found, "Key 'error.common.non_existent' not found in 'en' locale");
    }

    #[test]
    fn test_translation_for_portuguese_locale() {
        let translator = Translator::new("pt");

        // Test known translation
        let translation = translator.t("error.common.internal_server_error", None);
        println!("translation {}", translation);
        assert_eq!(translation, "Erro interno no servidor");

        // Test key not found
        let not_found = translator.t("error.common.non_existent", None);
        assert_eq!(not_found, "Key 'error.common.non_existent' not found in 'pt' locale");
    }

    #[test]
    fn test_translation_with_variables() {
        let translator = Translator::new("en");

        let mut variables = HashMap::new();
        variables.insert("resource", "User");

        let translation_with_vars = translator.t("error.common.not_found", Some(variables));
        assert_eq!(translation_with_vars, "User not found");
    }

    #[test]
    fn test_translation_module_not_found() {
        let translator = Translator::new("es");

        // Test loading a non-existent module
        let translation = translator.t("non_existent_module.common.internal_server_error", None);
        assert_eq!(
            translation,
            "Module 'non_existent_module' not found for 'es' locale"
        );
    }

    #[test]
    fn test_translation_section_not_found() {
        let translator = Translator::new("en");

        // Test section not found in translation file
        let translation = translator.t("error.non_existent_section.internal_server_error", None);
        assert_eq!(
            translation,
            "Section 'non_existent_section' not found in 'en' locale"
        );
    }
}

You can also test the mdware.

pub async fn test_handler(Extension(language): Extension<Language>) -> Json<serde_json::Value> {
    // Return a JSON response with the extracted language
    let response_message = match language.0.as_str() {
        "en" => "en",
        "pt" => "pt",
        "es" => "es",
        _ => "deafult",
    };

    Json(json!({ "message": response_message }))
}

#[cfg(test)]
mod tests {
    use crate::{
        constants::language::{EN, EN_US, ES, PT}, mdware::language::extract_client_language, tests::{test_handler, TRANSLATOR}  
    };
    use axum::{
        body::{to_bytes, Body}, http::Request, middleware::from_fn, Router
    };
    use hyper::StatusCode;
    use tower::ServiceExt; 
    use serde_json::{json, Value};

    #[tokio::test]
    async fn test_with_valid_accept_language_header() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        // Simulate a request with a valid Accept-Language header like
        let request = Request::builder()
            .header("Accept-Language", EN_US) // "en-US"
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();
        // println!("Response Body: {:?}", body_str);

        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": EN }));
    }

    #[tokio::test]
    async fn test_with_valid_accept_language_header_wiht_pt() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        let request = Request::builder()
            .header("Accept-Language", "pt")
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();

        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": PT }));
    }

    #[tokio::test]
    async fn test_with_valid_accept_language_header_wiht_pt_br() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        let request = Request::builder()
            .header("Accept-Language", "pt-BR")
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();

        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": PT }));
    }

    #[tokio::test]
    async fn test_with_valid_accept_language_header_wiht_es() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        let request = Request::builder()
            .header("Accept-Language", "es")
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();
        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": ES }));
    }

    #[tokio::test]
    async fn test_with_unsupported_language() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        let request = Request::builder()
            .header("Accept-Language", "fr")
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();

        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": EN }));
    }

    #[tokio::test]
    async fn test_without_accept_language_header() {
        let app = Router::new()
            .route("/", axum::routing::get(test_handler))
            .layer(from_fn(extract_client_language)); 

        let request = Request::builder()
            .body(Body::empty())
            .unwrap();

        let response = app.oneshot(request).await.unwrap();
        assert_eq!(response.status(), StatusCode::OK);

        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        let body_str = std::str::from_utf8(&body).unwrap();

        let body_json: Value = serde_json::from_str(body_str).unwrap();
        assert_eq!(body_json, json!({ "message": EN }));
    }
}

You can use these json translation files as references.

en.json
{
  "common": {
    "internal_server_error": "Internal server error",
    "not_authorized": "You are not authorized to use this resource",
    "not_found": "{resource} not found"
  },
}
pt.json
{
  "common": {
    "internal_server_error": "Erro interno no servidor",
    "not_authorized": "Você não está autorizado a usar este recurso",
    "not_found": "{resource} não encontrado"
  },
}
es.json
{
  "common": {
    "internal_server_error": "Error interno del servidor",
    "not_authorized": "No estás autorizado para usar este recurso",
    "not_found": "{resource} no encontrado"
  },
}

Conclusion

This translation system efficiently handles translations in a Rust application using static storage and thread-safe access. By leveraging OnceCell and Mutex, we can ensure that translation files are loaded once and cached, improving performance and reducing disk access. The t function allows for flexible translation retrieval with support for dynamic variables, making it a powerful tool for localization.

If you're building an application that requires localization, this approach provides a simple, scalable and efficient solution for managing translations. By using Rust’s powerful memory safety features, you can ensure that your translations are handled securely and efficiently across multiple threads.

We hope this post has helped you implement a simple translation system using Rust. We actively use Rust in production and are looking to hire more Rust developers.

Feel free to join our platform if you liked this post and support a company using Rust in production!