npm package: @oyy-gus/translate
Description: Google Translate unofficial ESM API wrapper
Author: oyy-gus
Latest version: 0.0.1

# @oyy-gus/translate

An unofficial Google Translate API wrapper built for **ESM (ECMAScript Module)** environments. This library provides a simple and intuitive interface to programmatically translate text using Google Translate, with support for auto language detection and language utility functions.

> ⚠️ This is **not** an official API from Google and may break without notice.

---

## ✨ Features

- 🌍 Translate text between hundreds of languages  
- 🧠 Automatic language detection  
- 📦 ESM and CommonJS support  
- 🔎 Language utility helpers: `getISOCode`, `isSupported`, etc.  
- 🔧 Uses Google Translate web endpoints  
- 🔐 Token generation to mimic browser behavior  

---

## 📦 Installation

```bash
npm install @oyy-gus/translate@latest
```

---

## 🚀 Usage

### ESM (Node.js 18+)

```js
import translate, { getISOCode, isSupported } from '@oyy-gus/translate';

const result = await translate('Bonjour', { from: 'fr', to: 'en' });

console.log(result.text); // "Hello"
console.log(result.from.language.iso); // "fr"
```

### CommonJS

```js
const translate = require('@oyy-gus/translate');

translate('Apa kabar?', { to: 'en' }).then((result) => {
  console.log(result.text); // "How are you?"
});
```

---

## 🛠️ API

### `translate(text, options)`

Translate a string of text from one language to another.

#### Parameters

| Name      | Type      | Default   | Description                                  |
|-----------|-----------|-----------|----------------------------------------------|
| `text`    | `string`  | —         | The text you want to translate               |
| `options` | `object`  | `{}`      | Optional configuration                       |
| `from`    | `string`  | `'auto'`  | Source language (ISO code or name)           |
| `to`      | `string`  | `'en'`    | Target language (ISO code or name)           |
| `raw`     | `boolean` | `false`   | Whether to return the raw response body      |

#### Returns

```ts
Promise<{
  text: string,
  from: {
    language: {
      didYouMean: boolean,
      iso: string
    },
    text: {
      autoCorrected: boolean,
      value: string,
      didYouMean: boolean
    }
  },
  raw?: any // if options.raw is true
}>
```

---

## 🧰 Language Helpers

### `translate.languages`

An object containing all supported language codes and their full names.

### `translate.getISOCode(language: string): string | null`

Returns the ISO code for a given language name or code.

```js
translate.getISOCode('Indonesian'); // 'id'
translate.getISOCode('id');         // 'id'
```

### `translate.isSupported(language: string): boolean`

Checks if a given language is supported.

```js
translate.isSupported('Korean'); // true
translate.isSupported('xx');     // false
```

---

## 🌐 Supported Languages

Use `translate.languages` to see the full list of supported languages and their ISO codes.

```js
console.log(translate.languages['fr']); // "French"
```

---

## 🔒 Disclaimer

This package uses undocumented Google Translate endpoints and may break if Google changes their internal APIs.

---

## 📄 License

MIT © oyy-gus