Internacionalização (i18n)

Documentação do sistema de internacionalização para uso interno no backend.

---

Índice

• Visão Geral
• Estrutura de Dados
• Preferências do Usuário
• API Endpoints
• Repository Layer
• Uso no Código
• Checklist para Novas Features

---

Visão Geral

O sistema de i18n permite que cada usuário escolha seu idioma preferido para a aplicação.

Características Principais

Aspecto	Valor
Idiomas	English (en-US), Portuguese (pt-BR)
Idioma Padrão	Portuguese (pt-BR)
Armazenamento	Tabela users, coluna lang
Escopo	Por usuário
Autorização	publicUsers (usuário autenticado)

---

Estrutura de Dados

Language

Localizado em: packages/common/src/i18n/types.ts

export enum Language {
  English = "en-US",
  Portuguese = "pt-BR",
}

export const AVAILABLE_LANGUAGES = Object.values(Language);

Valores Disponíveis

Enum Value	String Value	Descrição
English	en-US	Inglês
Portuguese	pt-BR	Português

Exportação

O tipo Language e a constante AVAILABLE_LANGUAGES são exportados via @gaio/common:

packages/common/src/export.ts

export * from "./i18n/types";

---

Preferências do Usuário

Schema do Usuário

Localizado em: packages/console/src/users/schemas/user.ts

import type { Language } from "@gaio/common";

export interface UserSchema extends Database.Schema {
  // ... outros campos ...

  /**
   * User preferred language.
   */
  lang?: Enum.Default<Language, Language.Portuguese>;

  // ... outros campos ...
}

Detalhes do Campo

Propriedade	Valor
Nome	lang
Tipo	Enum.Default<Language, Language.Portuguese>
Obrigatório	Não (opcional)
Default	Language.Portuguese (pt-BR)
Tabela	users

---

API Endpoints

GET /api/console/user-preferences

Retorna as preferências do usuário autenticado.

Authorizer: publicUsers

Response:

declare class UserPreferencesResponse implements Http.Response {
  status: 200;
  body: {
    lang?: Language | null;
  };
}

Exemplo de Response:

{
  "lang": "pt-BR"
}

---

PATCH /api/console/update-user-preferences

Atualiza as preferências do usuário autenticado.

Authorizer: publicUsers

Request Body:

{
  lang?: Language;
}

Exemplo de Request:

{
  "lang": "en-US"
}

Response: 204 No Content

---

Definição das Rotas

Localizado em: packages/console/src/users/routes.ts

export type UserRoutes = [
  // ... outras rotas ...
  {
    path: "GET /api/console/user-preferences";
    authorizer: typeof publicUsers;
    handler: typeof userPreferencesHandler;
  },
  {
    path: "PATCH /api/console/update-user-preferences";
    authorizer: typeof publicUsers;
    handler: typeof updateUserPreferencesHandler;
  },
];

---

Repository Layer

Localizado em: packages/console/src/users/repository.ts

UserRepository.preferences

Lê a preferência de idioma do usuário.

export const preferences = async (client: DbClient, userId: string) => {
  const user = await client.users.findOne({
    select: {
      lang: true,
    },
    where: {
      deleted_at: null,
      id: userId,
    },
  });

  return {
    lang: user?.lang ?? null,
  };
};

---

UserRepository.updatePreferences

Atualiza a preferência de idioma do usuário.

type UpdatePreferencesInput = {
  lang?: Language;
};

export const updatePreferences = async (
  client: DbClient,
  id: string,
  input: UpdatePreferencesInput,
) => {
  const now = new Date().toISOString();

  const response = await client.users.updateOne({
    select: {
      id: true,
    },
    data: {
      lang: input.lang,
      updated_at: now,
    },
    where: {
      deleted_at: null,
      id,
    },
  });

  return response?.id;
};

---

Uso no Código

Import do Tipo Language

import { Language, AVAILABLE_LANGUAGES } from "@gaio/common";

// Verificar se um valor é um idioma válido
const isValidLanguage = (value: string): value is Language => {
  return AVAILABLE_LANGUAGES.includes(value as Language);
};

// Usar em validações
if (!isValidLanguage(userInput)) {
  throw new HttpBadRequestError("Invalid language.");
}

Acessar Preferência do Usuário

import { UserRepository } from "../repository.js";

// Em um endpoint
export async function someHandler(
  request: SomeRequest,
  context: Service.Context<SomeProvider>,
): Promise<SomeResponse> {
  const { userId } = request.identity;
  const { consoleDb } = context;

  // Obter preferência de idioma
  const { lang } = await UserRepository.preferences(consoleDb, userId);

  // Usar o idioma (default pt-BR se null)
  const userLanguage = lang ?? Language.Portuguese;

  // ... usar userLanguage para formatação, mensagens, etc.
}

---

Checklist para Novas Features

• Verificar se a feature precisa exibir conteúdo localizado
• Usar o enum Language para campos de idioma (nunca strings literais)
• Respeitar a preferência do usuário (UserRepository.preferences)
• Usar Language.Portuguese como fallback quando lang for null
• Testar com ambos os idiomas (en-US e pt-BR)