PROYECTO DESTACADO
ggl-translate
A lightweight and modern Google Translate language selector for React.

Este contenido editorial está disponible en su idioma original.
🌍 @zyther/ggl-translate
A lightweight, modern Google Translate language selector for React.
Built with TypeScript. Designed for simplicity, customization, and seamless integration.
✨ 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
| Prop | Type | Default | Description |
|---|---|---|---|
defaultLanguage | string | "en" | The original language of your website. |
supportedLanguages | string | "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. |
className | string | "" | Additional CSS class for customization. |
style | React.CSSProperties | {} | Inline styles for the component. |
onLanguageChange | (language: string) => void | — | Callback invoked when the selected language changes. |
enableAutoDetection | boolean | true | Enables browser language detection. |
showNativeNames | boolean | true | Displays languages using their native names. |
placeholder | string | "Select Language" | Placeholder displayed by the selector. |
debug | boolean | false | Enables 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
| Code | Language | Native name |
|---|---|---|
en | English | English |
pt | Portuguese | Português |
es | Spanish | Español |
fr | French | Français |
de | German | Deutsch |
it | Italian | Italiano |
ru | Russian | Русский |
ja | Japanese | 日本語 |
ko | Korean | 한국어 |
zh | Chinese | 中文 |
ar | Arabic | العربية |
nl | Dutch | Nederlands |
pl | Polish | Polski |
tr | Turkish | Türkçe |
sv | Swedish | Svenska |
da | Danish | Dansk |
no | Norwegian | Norsk |
fi | Finnish | Suomi |
cs | Czech | Čeština |
el | Greek | Ελληνικά |
he | Hebrew | עברית |
hi | Hindi | हिन्दी |
hu | Hungarian | Magyar |
id | Indonesian | Bahasa Indonesia |
ms | Malay | Bahasa Melayu |
ro | Romanian | Română |
sk | Slovak | Slovenčina |
uk | Ukrainian | Українська |
vi | Vietnamese | Tiếng Việt |
th | Thai | ไทย |
ca | Catalan | Català |
eu | Basque | Euskara |
gl | Galician | Galego |
hr | Croatian | Hrvatski |
sr | Serbian | Српски |
sl | Slovenian | Slovenščina |
bg | Bulgarian | Български |
et | Estonian | Eesti |
lv | Latvian | Latviešu |
lt | Lithuanian | Lietuvių |
fa | Persian | فارسی |
bn | Bengali | বাংলা |
ta | Tamil | தமிழ் |
te | Telugu | తెలుగు |
ur | Urdu | اردو |
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:
- A custom language selector — a modern interface for choosing a language.
- Google Translate integration — uses Google's translation engine rather than implementing its own.
- Language persistence — retains the selected language across page reloads.
- Browser language detection — attempts to identify the visitor's preferred language.
- 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.
- Fork the repository.
- Create a branch for your changes.
- Make your changes and test them.
- 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!