# afritranslate

[Read in English](./README.md)

`afritranslate` est un outil CLI qui scanne les projets web, détecte les textes lisibles par les utilisateurs, puis génère des fichiers JSON de traduction pour l’intégration i18n. Google Cloud Translation est le fournisseur par défaut, et Groq reste disponible pour les paires de langues non africaines.

Les langues africaines prises en charge par Google, comme `fon`, `yo`, `ha`, `ig`, `sw`, `wo`, `ee`, `ln`, `bm`, `rw`, `xh` et `zu`, passent toujours par Google Cloud Translation, même si Groq est sélectionné.

## Installation

```bash
npm install -g afritranslate
```

Après l’installation, configure les clés API une seule fois :

```bash
afritranslate configure
```

L’assistant demande une clé Google Cloud Translation et, si besoin, une clé Groq. Les clés sont enregistrées dans `~/.afritranslate/config.json` avec des permissions limitées à l’utilisateur lorsque le système le permet.

## Clés API

### Google Cloud Translation

1. Crée ou sélectionne un projet Google Cloud.
2. Active l’API Cloud Translation.
3. Crée une clé API dans Google Cloud Console.
4. Restreins la clé à l’API Cloud Translation avant une utilisation en production.
5. Lance `afritranslate configure` et colle la clé.

Tu peux aussi fournir la clé au moment de la commande :

```bash
GOOGLE_TRANSLATE_API_KEY=ta_cle_google afritranslate translate --source fr --lang fon
```

Les variables acceptées sont `GOOGLE_TRANSLATE_API_KEY`, `GOOGLE_CLOUD_TRANSLATE_API_KEY` et `GOOGLE_API_KEY`.

### Groq Console

Groq est optionnel. Crée une clé dans Groq Console, enregistre-la avec `afritranslate configure`, ou fournis-la au lancement :

```bash
GROQ_API_KEY=ta_cle_groq afritranslate translate --provider groq --source en --lang fr
```

Le modèle Groq par défaut est `llama-3.3-70b-versatile`. Tu peux le changer avec `--groq-model` ou `GROQ_MODEL`.

## Utilisation

### 1. Scanner un projet

Place-toi dans le dossier du projet à traduire, puis lance le scan :

```bash
cd mon-projet
afritranslate scan --verbose
```

![sortie terminal du scan afritranslate](./docs/assets/scan-terminal.png)

Le scanner parcourt les dossiers et fichiers supportés, extrait les textes probablement visibles par l’utilisateur, détecte les langues, puis crée `afritranslate.scan.json` dans le dossier courant.

```bash
afritranslate scan ./src
afritranslate scan ./pages --verbose
afritranslate scan --output mon-scan.json
```

Le rapport de scan conserve chaque texte avec son fichier source, son numéro de ligne, sa langue détectée et le nom de la langue.

![rapport de scan afritranslate](./docs/assets/scan-report.png)

### 2. Traduire le scan

Traduire du français vers le fon :

```bash
afritranslate translate --source fr --lang fon
```

Traduire de l’anglais vers le français :

```bash
afritranslate translate --source en --lang fr
```

Utiliser un fichier d’entrée ou de sortie personnalisé :

```bash
afritranslate translate --input afritranslate.scan.json --output src/i18n/afritranslate.fon.json --source fr --lang fon
```

Forcer Google :

```bash
afritranslate translate --provider google --google-key TA_CLE_GOOGLE --source fr --lang fon
```

Utiliser Groq pour une paire de langues non africaines :

```bash
afritranslate translate --provider groq --groq-key TA_CLE_GROQ --source en --lang fr
```

La commande de traduction génère `afritranslate.json` par défaut.

```json
{
  "version": "0.0.3",
  "provider": "google",
  "sourceLanguage": "fr",
  "targetLanguage": "fon",
  "totalTexts": 42,
  "translatedTexts": 42,
  "translations": {
    "Bienvenue sur notre plateforme": "..."
  }
}
```

## Brancher Les Traductions Dans Le Site

`afritranslate` génère un JSON. Il ne réécrit pas automatiquement le code source du projet. Après la traduction, ajoute un petit helper `t()` et remplace les textes visibles par des clés de traduction.

### Structure recommandée

Génère le fichier de sortie dans ton dossier source :

```bash
mkdir -p src/i18n
afritranslate translate --output src/i18n/afritranslate.fon.json --source fr --lang fon
```

Crée `src/i18n/translate.ts` :

```typescript
import fon from './afritranslate.fon.json';

const translations = fon.translations as Record<string, string>;

export function t(key: string): string {
  return translations[key] ?? key;
}
```

Si TypeScript ne peut pas importer le JSON, active ceci dans `tsconfig.json` :

```json
{
  "compilerOptions": {
    "resolveJsonModule": true,
    "esModuleInterop": true
  }
}
```

### React

```tsx
import { t } from './i18n/translate';

export function HomePage() {
  return (
    <main>
      <h1>{t('Bienvenue sur notre plateforme')}</h1>
      <button>{t('Commencer')}</button>
    </main>
  );
}
```

### Vue 3

```vue
<script setup lang="ts">
import { t } from './i18n/translate';
</script>

<template>
  <main>
    <h1>{{ t('Bienvenue sur notre plateforme') }}</h1>
    <button>{{ t('Commencer') }}</button>
  </main>
</template>
```

### JavaScript simple

```javascript
import translations from './i18n/afritranslate.fon.json' assert { type: 'json' };

const t = (key) => translations.translations[key] ?? key;

document.querySelector('h1').textContent = t('Bienvenue sur notre plateforme');
```

### Sites statiques sans import JSON

Place le fichier JSON généré dans `public/`, puis charge-le au runtime :

```javascript
const response = await fetch('/afritranslate.fon.json');
const dictionary = await response.json();
const t = (key) => dictionary.translations[key] ?? key;
```

### Plusieurs langues

Génère un fichier par langue cible :

```bash
afritranslate translate --output src/i18n/afritranslate.fon.json --source fr --lang fon
afritranslate translate --output src/i18n/afritranslate.yo.json --source fr --lang yo
afritranslate translate --output src/i18n/afritranslate.en.json --source fr --lang en
```

Puis mappe les dictionnaires dans l’application :

```typescript
import fon from './afritranslate.fon.json';
import yo from './afritranslate.yo.json';
import en from './afritranslate.en.json';

const dictionaries = {
  fon: fon.translations,
  yo: yo.translations,
  en: en.translations,
} as const;

export type Locale = keyof typeof dictionaries;

export function t(key: string, locale: Locale = 'fon'): string {
  return dictionaries[locale][key] ?? key;
}
```

## Règles Du Scanner

Le scanner extrait :

- `.html` / `.htm` : noeuds texte et attributs visibles courants.
- `.js` / `.jsx` / `.ts` / `.tsx` : texte JSX, props visibles, appels i18n, et chaînes attachées à des clés orientées utilisateur comme `title`, `label`, `description`, `placeholder`, `pageTitle`, `emptyMessage` et `helperText`.
- `.vue` / `.svelte` : sections template et script.
- `.md` / `.mdx` : texte rédactionnel après suppression des blocs de code et de la syntaxe Markdown.
- `.json` : textes naturels sous des clés orientées utilisateur ou dans des fichiers locale/i18n/messages.

Le scanner ignore :

- `node_modules/`, `.git/`, `dist/`, `build/`, `.next/`, `.nuxt/`, `public/assets/`.
- Les fichiers générés comme `afritranslate.json` et `afritranslate.scan.json`.
- Les fichiers de configuration comme `package.json`, `tailwind.config.ts`, `vite.config.ts`, `next.config.js` et les fichiers similaires `*.config.*`.
- Les valeurs CSS et techniques comme `2rem`, `1400px`, `hsl(var(--neon-purple))`, `scale(1)`, les classes CSS, URLs, chemins, payload/schema/errors, et les chaînes trop courtes qui ne ressemblent pas à du texte naturel.

## Commandes

```bash
afritranslate configure
afritranslate configure --reset
afritranslate scan [dossier]
afritranslate scan --verbose
afritranslate translate --source fr --lang fon
afritranslate translate --provider groq --source en --lang fr
```

## Variables D’environnement

| Variable | Description |
|---|---|
| `GOOGLE_TRANSLATE_API_KEY` | Clé API Google Cloud Translation. |
| `GOOGLE_CLOUD_TRANSLATE_API_KEY` | Variable alternative pour la clé Google. |
| `GOOGLE_API_KEY` | Variable alternative pour la clé Google. |
| `GROQ_API_KEY` | Clé API Groq pour `--provider groq`. |
| `GROQ_MODEL` | Modèle Groq, par défaut `llama-3.3-70b-versatile`. |
| `AFRITRANSLATE_CONFIG` | Chemin personnalisé du fichier de configuration CLI. |

## Développement

```bash
npm install
npm run check
```

`npm run check` lance le typecheck TypeScript, compile `dist/`, puis exécute la suite de tests Node.

## Licence

MIT. Voir [LICENSE](./LICENSE).

## Mainteneur

- GitHub : [REBCDR07](https://github.com/REBCDR07)
- LinkedIn : [elton27](https://www.linkedin.com/in/elton27)
- Portfolio : [www.thekof.site](https://www.thekof.site)