forlogic-core 1.11.0 → 1.11.3

package/README.md

@@ -508,6 +508,150 @@ VITE_IS_QUALIEX=true
 
 ---
 
+## 🌐 Setup de Traduções para Projetos Consumidores
+
+O sistema de internacionalização (i18n) do `forlogic-core` carrega traduções dinamicamente do banco de dados Supabase. Para que funcione corretamente em projetos consumidores, siga os passos abaixo.
+
+### Requisitos
+
+| Requisito | Descrição |
+|-----------|-----------|
+| `VITE_SUPABASE_URL` | URL do projeto Supabase (mesma instância que contém `common.translations`) |
+| `VITE_SUPABASE_PUBLISHABLE_KEY` | Chave pública (anon key) do Supabase |
+| `i18next` | Peer dependency instalada |
+| `react-i18next` | Peer dependency instalada |
+| Tabela `common.translations` | Deve existir no Supabase com RLS pública para SELECT |
+
+### Passo 1: Instalar Peer Dependencies
+
+```bash
+npm install i18next@^25.0.0 react-i18next@^16.0.0
+```
+
+### Passo 2: Configurar Variáveis de Ambiente
+
+No arquivo `.env` do projeto consumidor:
+
+```env
+# Deve apontar para a mesma instância Supabase que contém common.translations
+VITE_SUPABASE_URL=https://seu-projeto.supabase.co
+VITE_SUPABASE_PUBLISHABLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+### Passo 3: Aguardar i18n Inicializar no main.tsx
+
+**⚠️ CRÍTICO**: O `main.tsx` deve aguardar o i18n carregar as traduções antes de renderizar a aplicação.
+
+```tsx
+// src/main.tsx
+import { createRoot } from 'react-dom/client';
+import { i18n } from 'forlogic-core';
+import App from './App';
+import './index.css';
+
+const renderApp = () => {
+  createRoot(document.getElementById("root")!).render(<App />);
+};
+
+// ✅ Aguardar i18n inicializar antes de renderizar
+if (i18n.isInitialized) {
+  renderApp();
+} else {
+  i18n.on('initialized', renderApp);
+}
+```
+
+**❌ ERRADO** - Renderizar sem aguardar (mostrará apenas chaves):
+
+```tsx
+// ❌ NÃO FAÇA ISSO - traduções não estarão prontas
+createRoot(document.getElementById("root")!).render(<App />);
+```
+
+### Passo 4: Usar CoreProviders no App.tsx
+
+```tsx
+// src/App.tsx
+import { CoreProviders } from 'forlogic-core';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+function App() {
+  return (
+    <CoreProviders>
+      <BrowserRouter>
+        <Routes>
+          {/* Suas rotas */}
+        </Routes>
+      </BrowserRouter>
+    </CoreProviders>
+  );
+}
+
+export default App;
+```
+
+### Passo 5: Usar useTranslation do forlogic-core
+
+```tsx
+// ❌ ERRADO - Cria instância separada
+import { useTranslation } from 'react-i18next';
+
+// ✅ CORRETO - Usa mesma instância configurada
+import { useTranslation } from 'forlogic-core';
+
+function MeuComponente() {
+  const { t } = useTranslation();
+  return <h1>{t('minha.chave')}</h1>;
+}
+```
+
+### Troubleshooting
+
+#### Traduções mostram apenas as chaves (ex: `common.save` ao invés de "Salvar")
+
+| Causa | Solução |
+|-------|---------|
+| `main.tsx` não aguarda i18n | Adicionar verificação `i18n.isInitialized` conforme Passo 3 |
+| Peer dependencies faltando | Instalar `i18next` e `react-i18next` |
+| Variáveis de ambiente incorretas | Verificar `VITE_SUPABASE_URL` e `VITE_SUPABASE_PUBLISHABLE_KEY` |
+| Supabase diferente | Verificar se aponta para a mesma instância com `common.translations` |
+| Import de `react-i18next` direto | Usar import de `forlogic-core` |
+
+#### Debug: Verificar se traduções foram carregadas
+
+```tsx
+import { i18n } from 'forlogic-core';
+
+// No console
+console.log('i18n initialized:', i18n.isInitialized);
+console.log('Current language:', i18n.language);
+console.log('Loaded resources:', i18n.store.data);
+```
+
+#### Habilitar modo debug
+
+Adicione no `.env`:
+
+```env
+VITE_I18N_DEBUG_MODE=true
+```
+
+Com debug ativo, chaves traduzidas aparecem como `[chave ✅]` e chaves não encontradas como `[⚠️ chave]`.
+
+### Checklist de Configuração
+
+```markdown
+- [ ] Instalou `i18next@^25.0.0` e `react-i18next@^16.0.0`?
+- [ ] Configurou `VITE_SUPABASE_URL` apontando para a instância correta?
+- [ ] Configurou `VITE_SUPABASE_PUBLISHABLE_KEY`?
+- [ ] O `main.tsx` aguarda `i18n.isInitialized` antes de renderizar?
+- [ ] O `App.tsx` usa `CoreProviders`?
+- [ ] Todos os imports de `useTranslation` são de `forlogic-core`?
+- [ ] A tabela `common.translations` existe e tem RLS pública para SELECT?
+```
+
+---
+
 ## 🚀 Quick Setup: CoreProviders
 
 O `CoreProviders` é um componente que encapsula todos os providers essenciais da biblioteca, simplificando drasticamente a configuração de novos projetos.

package/dist/README.md

@@ -508,6 +508,150 @@ VITE_IS_QUALIEX=true
 
 ---
 
+## 🌐 Setup de Traduções para Projetos Consumidores
+
+O sistema de internacionalização (i18n) do `forlogic-core` carrega traduções dinamicamente do banco de dados Supabase. Para que funcione corretamente em projetos consumidores, siga os passos abaixo.
+
+### Requisitos
+
+| Requisito | Descrição |
+|-----------|-----------|
+| `VITE_SUPABASE_URL` | URL do projeto Supabase (mesma instância que contém `common.translations`) |
+| `VITE_SUPABASE_PUBLISHABLE_KEY` | Chave pública (anon key) do Supabase |
+| `i18next` | Peer dependency instalada |
+| `react-i18next` | Peer dependency instalada |
+| Tabela `common.translations` | Deve existir no Supabase com RLS pública para SELECT |
+
+### Passo 1: Instalar Peer Dependencies
+
+```bash
+npm install i18next@^25.0.0 react-i18next@^16.0.0
+```
+
+### Passo 2: Configurar Variáveis de Ambiente
+
+No arquivo `.env` do projeto consumidor:
+
+```env
+# Deve apontar para a mesma instância Supabase que contém common.translations
+VITE_SUPABASE_URL=https://seu-projeto.supabase.co
+VITE_SUPABASE_PUBLISHABLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+### Passo 3: Aguardar i18n Inicializar no main.tsx
+
+**⚠️ CRÍTICO**: O `main.tsx` deve aguardar o i18n carregar as traduções antes de renderizar a aplicação.
+
+```tsx
+// src/main.tsx
+import { createRoot } from 'react-dom/client';
+import { i18n } from 'forlogic-core';
+import App from './App';
+import './index.css';
+
+const renderApp = () => {
+  createRoot(document.getElementById("root")!).render(<App />);
+};
+
+// ✅ Aguardar i18n inicializar antes de renderizar
+if (i18n.isInitialized) {
+  renderApp();
+} else {
+  i18n.on('initialized', renderApp);
+}
+```
+
+**❌ ERRADO** - Renderizar sem aguardar (mostrará apenas chaves):
+
+```tsx
+// ❌ NÃO FAÇA ISSO - traduções não estarão prontas
+createRoot(document.getElementById("root")!).render(<App />);
+```
+
+### Passo 4: Usar CoreProviders no App.tsx
+
+```tsx
+// src/App.tsx
+import { CoreProviders } from 'forlogic-core';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+function App() {
+  return (
+    <CoreProviders>
+      <BrowserRouter>
+        <Routes>
+          {/* Suas rotas */}
+        </Routes>
+      </BrowserRouter>
+    </CoreProviders>
+  );
+}
+
+export default App;
+```
+
+### Passo 5: Usar useTranslation do forlogic-core
+
+```tsx
+// ❌ ERRADO - Cria instância separada
+import { useTranslation } from 'react-i18next';
+
+// ✅ CORRETO - Usa mesma instância configurada
+import { useTranslation } from 'forlogic-core';
+
+function MeuComponente() {
+  const { t } = useTranslation();
+  return <h1>{t('minha.chave')}</h1>;
+}
+```
+
+### Troubleshooting
+
+#### Traduções mostram apenas as chaves (ex: `common.save` ao invés de "Salvar")
+
+| Causa | Solução |
+|-------|---------|
+| `main.tsx` não aguarda i18n | Adicionar verificação `i18n.isInitialized` conforme Passo 3 |
+| Peer dependencies faltando | Instalar `i18next` e `react-i18next` |
+| Variáveis de ambiente incorretas | Verificar `VITE_SUPABASE_URL` e `VITE_SUPABASE_PUBLISHABLE_KEY` |
+| Supabase diferente | Verificar se aponta para a mesma instância com `common.translations` |
+| Import de `react-i18next` direto | Usar import de `forlogic-core` |
+
+#### Debug: Verificar se traduções foram carregadas
+
+```tsx
+import { i18n } from 'forlogic-core';
+
+// No console
+console.log('i18n initialized:', i18n.isInitialized);
+console.log('Current language:', i18n.language);
+console.log('Loaded resources:', i18n.store.data);
+```
+
+#### Habilitar modo debug
+
+Adicione no `.env`:
+
+```env
+VITE_I18N_DEBUG_MODE=true
+```
+
+Com debug ativo, chaves traduzidas aparecem como `[chave ✅]` e chaves não encontradas como `[⚠️ chave]`.
+
+### Checklist de Configuração
+
+```markdown
+- [ ] Instalou `i18next@^25.0.0` e `react-i18next@^16.0.0`?
+- [ ] Configurou `VITE_SUPABASE_URL` apontando para a instância correta?
+- [ ] Configurou `VITE_SUPABASE_PUBLISHABLE_KEY`?
+- [ ] O `main.tsx` aguarda `i18n.isInitialized` antes de renderizar?
+- [ ] O `App.tsx` usa `CoreProviders`?
+- [ ] Todos os imports de `useTranslation` são de `forlogic-core`?
+- [ ] A tabela `common.translations` existe e tem RLS pública para SELECT?
+```
+
+---
+
 ## 🚀 Quick Setup: CoreProviders
 
 O `CoreProviders` é um componente que encapsula todos os providers essenciais da biblioteca, simplificando drasticamente a configuração de novos projetos.