Voltar aos projetos

PROJETO EM DESTAQUE

ggl-translate

A lightweight and modern Google Translate language selector for React.

TypeScriptCSS
ggl-translate

Este conteúdo editorial está disponível no idioma original.

🌍 @zyther/ggl-translate

A lightweight, modern Google Translate language selector for React.
Built with TypeScript. Designed for simplicity, customization, and seamless integration.

npm version MIT License TypeScript React 18+


✨ Features

  • 🌍 Google Translate integration — translate your website using Google's translation engine.
  • 🎨 Modern language selector — a customizable interface that fits your application.
  • 🌓 Theme support — light, dark, and system themes.
  • 🚀 Zero runtime dependencies — no additional runtime packages required.
  • ⚛️ React 18+ support — built for modern React applications.
  • 📘 TypeScript support — includes TypeScript declarations.
  • 🔄 Automatic language detection — detects the visitor's browser language.
  • 🌐 Multiple languages — configure the languages available to your users.
  • 📱 Responsive design — designed for desktop, tablet, and mobile devices.
  • 🧩 Easy integration — add a language selector to an existing React application.
  • 🎯 Native language names and flags — make language selection more intuitive.
  • 💾 Persistent language selection — retains the selected language across page reloads.

📦 Installation

Install the package using your preferred package manager.

npm install @zyther/ggl-translate

Alternatively, use another package manager:

pnpm add @zyther/ggl-translate
yarn add @zyther/ggl-translate

Peer dependencies: React and React DOM must be available in your application. This package does not bundle its own copies of them.

🚀 Quick Start

Import the component and its stylesheet into your React application.

import { GoogleTranslate } from '@zyther/ggl-translate';
import '@zyther/ggl-translate/styles.css';

function App() {
  return (
    <main>
      <h1>Welcome to my website</h1>

      <GoogleTranslate
        defaultLanguage="en"
        supportedLanguages="en,pt,es,fr,de,it,ja,ko,zh"
      />
    </main>
  );
}

export default App;

That's it! The component provides the language selector and initializes the embedded Google Translate integration in the browser.

⚙️ Configuration

Customize the selector to match your application's needs.

<GoogleTranslate
  defaultLanguage="en"
  supportedLanguages="en,pt,es,fr,de,it,ja,ko,zh"
  theme={{ mode: 'system' }}
  enableAutoDetection
  showNativeNames
  placeholder="Select Language"
/>

Props

PropTypeDefaultDescription
defaultLanguagestring"en"The original language of your website.
supportedLanguagesstring"pt,en,es,fr,it,ru"Comma-separated list of available language codes.
theme{ mode: 'light' | 'dark' | 'system' }{ mode: 'system' }Controls the selector's appearance.
classNamestring""Additional CSS class for customization.
styleReact.CSSProperties{}Inline styles for the component.
onLanguageChange(language: string) => void—Callback invoked when the selected language changes.
enableAutoDetectionbooleantrueEnables browser language detection.
showNativeNamesbooleantrueDisplays languages using their native names.
placeholderstring"Select Language"Placeholder displayed by the selector.
debugbooleanfalseEnables debug logging.

🌍 Supported Languages

The package exports a predefined list of commonly used languages, along with their associated flags.

import {
  LANGUAGES,
  LANGUAGE_FLAGS,
} from '@zyther/ggl-translate';

Available Languages

CodeLanguageNative name
enEnglishEnglish
ptPortuguesePortuguês
esSpanishEspañol
frFrenchFrançais
deGermanDeutsch
itItalianItaliano
ruRussianРусский
jaJapanese日本語
koKorean한국어
zhChinese中文
arArabicالعربية
nlDutchNederlands
plPolishPolski
trTurkishTürkçe
svSwedishSvenska
daDanishDansk
noNorwegianNorsk
fiFinnishSuomi
csCzechČeština
elGreekΕλληνικά
heHebrewעברית
hiHindiहिन्दी
huHungarianMagyar
idIndonesianBahasa Indonesia
msMalayBahasa Melayu
roRomanianRomână
skSlovakSlovenčina
ukUkrainianУкраїнська
viVietnameseTiếng Việt
thThaiไทย
caCatalanCatalà
euBasqueEuskara
glGalicianGalego
hrCroatianHrvatski
srSerbianСрпски
slSlovenianSlovenščina
bgBulgarianБългарски
etEstonianEesti
lvLatvianLatviešu
ltLithuanianLietuvių
faPersianفارسی
bnBengaliবাংলা
taTamilதமிழ்
teTeluguతెలుగు
urUrduاردو

Custom Language Selection

You can configure the available languages using their language codes.

<GoogleTranslate
  defaultLanguage="en"
  supportedLanguages="en,pt,es,fr,de,it,ja,ko,zh,ar,hi,uk"
/>

You can also pass other language codes supported by Google Translate.

Note: The language codes must be supported by the underlying Google Translate integration.

🎨 Themes

Choose between three theme modes to match your application's design.

Light Theme

<GoogleTranslate theme={{ mode: 'light' }} />

Dark Theme

<GoogleTranslate theme={{ mode: 'dark' }} />

System Theme

<GoogleTranslate theme={{ mode: 'system' }} />

The system mode follows the user's operating system or browser color scheme.

🔍 Automatic Language Detection

By default, the component attempts to detect the visitor's browser language.

<GoogleTranslate
  defaultLanguage="en"
  supportedLanguages="en,pt,es,fr,de"
  enableAutoDetection
/>

If the detected language is not included in supportedLanguages, the component falls back to defaultLanguage.

Disable Automatic Detection

<GoogleTranslate
  defaultLanguage="en"
  enableAutoDetection={false}
/>

This allows you to control the initial language without relying on browser language detection.

🎯 Listening for Language Changes

Use the onLanguageChange callback to respond to language selections.

<GoogleTranslate
  defaultLanguage="en"
  supportedLanguages="en,pt,es,fr"
  onLanguageChange={(language) => {
    console.log('Language changed:', language);
  }}
/>

This can be useful when you need to synchronize the selected language with other parts of your application.

📱 Responsive Design & Customization

The selector is designed for:

  • 💻 Desktop screens
  • 📱 Mobile devices
  • 📲 Tablets
  • 👆 Touch interfaces

You can customize its appearance using the className and style props.

Example

<GoogleTranslate
  className="my-language-selector"
/>
.my-language-selector {
  max-width: 320px;
  width: 100%;
}

Use your own CSS to integrate the selector into your application's existing design system.

🧠 How It Works

@zyther/ggl-translate combines a custom React interface with Google's embedded website translation functionality.

The package provides:

  1. A custom language selector — a modern interface for choosing a language.
  2. Google Translate integration — uses Google's translation engine rather than implementing its own.
  3. Language persistence — retains the selected language across page reloads.
  4. Browser language detection — attempts to identify the visitor's preferred language.
  5. Theme customization — supports light, dark, and system appearance modes.

The underlying Google Translate widget is kept out of the main visual interface so that the package can provide its own selector instead of relying on Google's default UI.

When a user selects another language, the package persists the selection and reloads the page so Google Translate can initialize with the requested language.

⚠️ Important Notes

This package relies on Google's embedded Website Translator functionality.

  • The translation engine is provided by Google, not by this package.
  • Translation behavior and availability depend on Google's services.
  • Changes to Google's embedded translation functionality may affect compatibility.
  • This package does not provide its own machine-translation engine.
  • Browser behavior, network conditions, and Google's integration may affect the translation experience.

Important: Google controls the underlying translation service. Compatibility with future changes to that service cannot be guaranteed.

🛠️ Development

Want to contribute or explore the source code? Get started locally.

1. Clone the repository

git clone https://github.com/zytherdev/ggl-translate.git
cd ggl-translate

2. Install dependencies

npm install

3. Start the development environment

npm run dev

4. Build the package

npm run build:lib

Prerequisites: Make sure you have Node.js and npm installed before starting development.

📘 TypeScript Support

The package includes TypeScript declarations for its public API.

import {
  GoogleTranslate,
  LANGUAGES,
  LANGUAGE_FLAGS,
} from '@zyther/ggl-translate';

This enables type-aware development and editor autocomplete when using the package in TypeScript projects.

🤝 Contributing

Contributions are welcome!

Whether you want to report a bug, suggest a feature, improve the documentation, or submit a pull request, your contributions can help improve the project.

  1. Fork the repository.
  2. Create a branch for your changes.
  3. Make your changes and test them.
  4. Submit a pull request.

For bugs and feature requests, open an issue in the project repository.

📄 License

This project is licensed under the MIT License.

Copyright © zytherdev

See the MIT License for details.


Built with ❤️ by Zyther
If you find this package useful, consider giving the repository a ⭐ on GitHub!

SEU PRÓXIMO CAPÍTULO

Uma ideia que merece sair do papel?
Vamos torná-la realidade.

Conte o que você tem em mente. Vamos ajudar a encontrar a direção técnica certa.