fonika_translate

Package npm pour applications web: traduction de page Google Translate + voix (speech-to-text et text-to-speech).

Objectif: permettre a une equipe web d'ajouter rapidement la traduction avec une API simple.

Nouveau: Client API 229Langues (Architecture 2026)

Le package expose maintenant un client HTTP pour l'API backend avec la meme architecture que le SDK Flutter:

1. Authorization: Bearer <authorizationToken>
2. X-API-Key: <apiToken>

Exemple rapide:

import { createApiClient } from "fonika_translate";

const api = createApiClient({
  baseUrl: "https://ronaldodev-api.hf.space",
  authorizationToken: process.env.AUTHORIZATION_TOKEN!,
  apiToken: process.env.API_KEY!,
});

const translated = await api.translate({
  text: "Bonjour",
  from_lang: "fr",
  to_lang: "en",
});

console.log(translated);

Methodes exposees par FonikaApiClient:

1. health()
2. translate()
3. translateBatch()
4. getLanguages()
5. getVoiceLanguages()
6. getCacheStats()
7. clearCache()
8. tts()
9. stt()
10. translateTextFile()
11. translatePdf()
12. extractPdfText()

Demarrage En 2 Minutes

npm install fonika_translate

Exemple minimum:

<div id="lang-buttons"></div>

<script type="module">
  import { createTranslator, createLanguageButtons } from "fonika_translate";

  const translator = await createTranslator({ pageLanguage: "fr" });

  createLanguageButtons({
    translator,
    container: "lang-buttons",
    flag: true,
    languages: [
      { code: "de", label: "Allemand" },
      { code: "en", label: "Anglais" },
      { code: "es", label: "Espagnol" },
    ],
  });
</script>

Cas Concret 1: Traduire Une Page Avec Boutons

<div id="lang-buttons"></div>

<script type="module">
  import { createTranslator, createLanguageButtons } from "fonika_translate";

  const translator = await createTranslator({
    pageLanguage: "fr",
    containerId: "google_translate_element2",
  });

  createLanguageButtons({
    translator,
    container: "lang-buttons",
    flag: true,
    buttonClassName: "lang-btn",
    languages: [
      { code: "de", label: "Allemand" },
      { code: "fon", label: "Fon" },
      { code: "es", label: "Espagnol" },
      { code: "pt", label: "Portugais" },
      { code: "it", label: "Italien" },
      { code: "en", label: "Anglais" },
    ],
  });
</script>

Ce que fait cet exemple:

1. Charge Google Translate.
2. Cree des boutons de langues.
3. Change la langue au clic.

Cas Concret 2: Parler En Francais, Obtenir Traduction + Lecture Audio

<div id="speech-zone"></div>

<script type="module">
  import {
    createSpeechTranslator,
    createSpeechTranslatorComponent,
  } from "fonika_translate";

  const speechTranslator = await createSpeechTranslator({
    sourceLanguage: "fr",
    targetLanguage: "en",
    autoSpeak: true,
  });

  createSpeechTranslatorComponent({
    container: "speech-zone",
    speechTranslator,
    labels: {
      start: "Parler puis traduire",
      listening: "Ecoute...",
      source: "Texte source",
      target: "Texte traduit",
    },
  });
</script>

Ce que fait cet exemple:

1. Ecoute le micro en francais.
2. Traduit en anglais.
3. Lit la traduction a voix haute.

Cas Concret 3: Test TTS Manuel (Sans Micro)

Utile pour verifier le text-to-speech meme si le speech-to-text n'est pas disponible.

<input id="tts-input" value="Hello from fonika translate" />
<button id="tts-play">Lire</button>
<button id="tts-stop">Arreter</button>

<script type="module">
  import { createSpeechTranslator } from "fonika_translate";

  const speechTranslator = await createSpeechTranslator({
    sourceLanguage: "fr",
    targetLanguage: "en",
    autoSpeak: false,
  });

  document.getElementById("tts-play").addEventListener("click", async () => {
    const text = document.getElementById("tts-input").value;
    await speechTranslator.speak(text, "en-US");
  });

  document.getElementById("tts-stop").addEventListener("click", () => {
    speechTranslator.stopSpeaking();
  });
</script>

Test Local Sans Publication npm

Quand vous developpez le package localement:

npm run build
npm pack
cd local-test-app
npm install --force ../fonika_translate-1.0.0.tgz
npm run dev

API Rapide

Traduction de page:

1. createTranslator(options)
2. translator.translateTo("fr|en") ou translator.translateTo("en")
3. createLanguageButtons(options)

Voix:

1. createSpeechTranslator(options)
2. speechTranslator.listenTranslateSpeak()
3. speechTranslator.translateText("...")
4. speechTranslator.speak("...")
5. createSpeechTranslatorComponent(options)

Options principales (traduction de page):

1. pageLanguage: langue source de la page (defaut: fr)
2. containerId: id du conteneur Google caché (defaut: google_translate_element2)
3. autoDisplay: affichage auto Google (defaut: false)

Options principales (voix):

1. sourceLanguage: langue reconnue au micro (obligatoire)
2. targetLanguage: langue de traduction (obligatoire)
3. autoSpeak: lire automatiquement la traduction (defaut: true)
4. voiceLanguage: langue de la voix de synthese (defaut: targetLanguage)

CommonJS

const { FonikaTranslator, createLanguageButtons } = require("fonika_translate");

(async () => {
  const translator = new FonikaTranslator({ pageLanguage: "fr" });
  await translator.init();

  createLanguageButtons({
    translator,
    container: "lang-buttons",
    flag: true,
    languages: ["de", "es", "pt", "it"],
  });
})();

TypeScript

Le package expose les types automatiquement depuis dist/index.d.ts.

Tests Et Release

npm test
npm run build
npm run release:check

Depannage Rapide

1. Le TTS ne parle pas: Navigateur muet, volume systeme, ou absence de geste utilisateur. Tester avec le bouton Lire apres un clic sur la page.

2. Le STT ne demarre pas: Verifier permission micro et support navigateur (SpeechRecognition ou webkitSpeechRecognition).

3. Le package local ne se met pas a jour: Regenerez le tgz avec npm pack puis reinstallez avec npm install --force ../fonika_translate-1.0.0.tgz.

4. Le panneau Google de feedback reapparait: Le package le masque automatiquement, mais faire un hard refresh apres mise a jour locale.

Notes Importantes

1. Fonctionne uniquement en navigateur.
2. Le widget Google Translate peut evoluer selon les politiques Google.
3. Le support voix depend des APIs Web Speech disponibles sur le navigateur cible.