simple_translator 1.0.0

A simple and lightweight package for translating text using the Google Translate API.

📦 simple_translator

A simple and lightweight Google Translate API client for Dart and Flutter. This package provides a straightforward way to translate text between various languages. It is suitable for pure Dart (CLI, backend, servers) and Flutter (iOS, Android, Web, macOS, Windows, Linux) projects.

⚠️ Disclaimer: This package uses an unofficial Google Translate API endpoint. While it works reliably, functionality might be subject to network policies or rate limits by Google's service.

---

✨ Features

• 🔤 Text Translation: Translate text from a source language to any target language.
• 🌐 Automatic Language Detection: Automatically detects the source language if not specified (from: 'auto').
• 📦 String Extension: Convenient .translate() extension method directly on String.
• ⚡ Batch Translation: Translate multiple phrases sequentially using translateBatch().
• ⏱️ Timeout Support: Set custom timeouts for network requests.
• 💉 Dependency Injection: Inject custom http.Client for testing with MockClient or setting up custom proxies.
• 📚 Language List & Helpers: Easy lookup by code (byCode) or by name (byName).
• 🚨 Error Handling: Throws structured exceptions for unsupported languages or network issues.

---

🚀 Installation

Add simple_translator to your pubspec.yaml:

dependencies:
  simple_translator: ^1.0.0

Then run:

dart pub get
# or
flutter pub get

---

📖 Usage

✅ Basic Translation

import 'package:simple_translator/simple_translator.dart';

void main() async {
  final translator = GoogleTranslator();

  try {
    var translation = await translator.translate(
      "Hello world",
      from: 'en',
      to: 'es',
    );

    print('Original Text: ${translation.source}');
    print('Translated Text: ${translation.text}');
    print('Source Language: ${translation.sourceLanguage.name}');
    print('Target Language: ${translation.targetLanguage.name}');
  } catch (e) {
    print('Translation error: $e');
  } finally {
    translator.close();
  }
}

---

🤖 Automatic Language Detection

import 'package:simple_translator/simple_translator.dart';

void main() async {
  final translator = GoogleTranslator();

  try {
    var autoTranslation = await translator.translate(
      "Bonjour le monde", // French
      to: 'de',           // Translate to German
    );

    print('Original Text: ${autoTranslation.source}');
    print('Translated Text: ${autoTranslation.text}');
    print('Detected Language: ${autoTranslation.sourceLanguage.name}');
    print('Target Language: ${autoTranslation.targetLanguage.name}');
  } catch (e) {
    print('Translation error: $e');
  }
}

---

🧩 Using String Extension

import 'package:simple_translator/simple_translator.dart';

void main() async {
  try {
    var english = await "안녕하세요".translate(to: 'en');
    print(english.text); // Hello

    var french = await "How are you?".translate(to: 'fr');
    print(french.text); // Comment allez-vous ?
  } catch (e) {
    print('Translation error: $e');
  }
}

---

⚡ Batch Translation

import 'package:simple_translator/simple_translator.dart';

void main() async {
  final translator = GoogleTranslator();

  final results = await translator.translateBatch(
    ['Good morning', 'Thank you', 'Goodbye'],
    from: 'en',
    to: 'es',
  );

  for (final result in results) {
    print('${result.source} -> ${result.text}');
  }
}

---

🌍 Supported Languages

import 'package:simple_translator/simple_translator.dart';

void main() {
  print(LanguageList.contains('es'));        // true
  print(LanguageList.contains('Spanish'));   // true
  print(LanguageList.contains('xyz'));       // false

  final english = LanguageList.byCode('en');
  print(english?.name); // English
  print(english?.code); // en

  final spanish = LanguageList.byName('Spanish');
  print(spanish?.code); // es

  try {
    final lang = LanguageList()['invalid_code'];
    print(lang);
  } on LanguageNotSupportedException catch (e) {
    print(e.msg); // invalid_code is not a supported language.
  }
}

---

⚙️ Custom Client & Testing

You can inject a custom http.Client (e.g. for testing with MockClient or setting up custom headers/proxies):

import 'package:http/http.dart' as http;
import 'package:simple_translator/simple_translator.dart';

final translator = GoogleTranslator(
  httpClient: http.Client(),
  client: ClientType.siteGT,
);

ClientType.siteGT is the default web client. ClientType.extensionGT uses the browser extension endpoint.

---

⚠️ Error Handling

The translate method may throw:

• LanguageNotSupportedException: If the from or to language code is not recognized.
• http.ClientException: For network issues or HTTP errors.
• TimeoutException: When a specified timeout expires.

---

👤 Author

Md. Rahul Reza 🌐 rahulreza.com 📧 [e-mail]

---

📄 License

This project is licensed under the MIT License.