{"id":13895251,"url":"https://github.com/FreddieDeWitt/google-translate-extended-api","last_synced_at":"2025-07-17T10:33:20.847Z","repository":{"id":51384013,"uuid":"146886264","full_name":"FreddieDeWitt/google-translate-extended-api","owner":"FreddieDeWitt","description":"Free Google Translate API - get word definitions, examples, synonyms and a lot more","archived":false,"fork":false,"pushed_at":"2023-12-02T12:28:37.000Z","size":43,"stargazers_count":51,"open_issues_count":4,"forks_count":14,"subscribers_count":0,"default_branch":"master","last_synced_at":"2024-10-29T01:15:19.549Z","etag":null,"topics":["google-translate-api","nodejs","npm-module"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FreddieDeWitt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-08-31T11:59:44.000Z","updated_at":"2024-09-13T02:07:43.000Z","dependencies_parsed_at":"2024-04-16T01:53:03.498Z","dependency_job_id":null,"html_url":"https://github.com/FreddieDeWitt/google-translate-extended-api","commit_stats":{"total_commits":16,"total_committers":1,"mean_commits":16.0,"dds":0.0,"last_synced_commit":"730652924a8abf235bb5e15bbaf903d63c72463e"},"previous_names":["freddiedewitt/extended-google-translate-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreddieDeWitt%2Fgoogle-translate-extended-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreddieDeWitt%2Fgoogle-translate-extended-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreddieDeWitt%2Fgoogle-translate-extended-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreddieDeWitt%2Fgoogle-translate-extended-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FreddieDeWitt","download_url":"https://codeload.github.com/FreddieDeWitt/google-translate-extended-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226255376,"owners_count":17595859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["google-translate-api","nodejs","npm-module"],"created_at":"2024-08-06T18:02:05.609Z","updated_at":"2024-11-25T00:31:19.502Z","avatar_url":"https://github.com/FreddieDeWitt.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# google-translate-extended-api\r\n\r\nFree Extended Google Translate API - get word definitions, examples, synonyms and a lot more\r\n\r\n# Updates\r\n\r\n- Fix word type being null\r\n- Using code from @vitalets/google-translate-api, as the request to Google Translate and the responce changed.\r\n- Change the available settings options, as the response from Google Translate has changed - `collocations` are not available anymore, and `synonyms` are changed to `definitionSynonyms` and they are stored inside the definitions (see the API for new [Fields](#fields))\r\n\r\n## Table of Contents\r\n\r\n- [Features](#features)\r\n- [Installation](#installation)\r\n- [Usage examples](#usage-examples)\r\n- [API](#api)\r\n  - [translate(text, sourceLang, destLang, dataOptions)](#translatetext-sourcelang-destlang-dataoptions)\r\n    - [Arguments](#arguments)\r\n    - [Response](#response)\r\n  - [dataOptions Object](#dataoptions-object)\r\n    - [Fields](#fields)\r\n    - [Defaults](#defaults)\r\n  - [Response Object](#response-object)\r\n- [Contacts](#contacts)\r\n\r\n## Features\r\n\r\n- Fast and efficient - each request consumes about 1.5 Kb\r\n\r\n- Rich word information - definitions, examples, synonyms, collocations and multiple translations\r\n\r\n- Uses the same request that translate.google.com do\r\n\r\n## Installation\r\n\r\n```npm i google-translate-extended-api```\r\n\r\n## Usage examples\r\n\r\nThe first argument is query (it can be a single word or a sentence).  \r\nThe second argument is a source language of query, third - desired translation language.  \r\nThe fourth is optional - it is [`dataOptions`](#dataoptions-object) object.  \r\n\r\n``` js\r\n\r\nconst translate = require('google-translate-extended-api');\r\n\r\ntranslate(\"parlous\", \"en\", \"de\").then((res) =\u003e {\r\n    console.log(JSON.stringify(res, undefined, 2));\r\n}).catch(console.log);\r\n\r\n```\r\n\r\n\r\nResult is:\r\n\r\n``` json\r\n\r\n{\r\n  \"word\": \"parlous\",\r\n  \"translation\": \"parlous\",\r\n  \"wordTranscription\": \"ˈpärləs\",\r\n  \"translationTranscription\": null,\r\n  \"translations\": {\r\n    \"adjective\": [\r\n      \"gefährlich\",\r\n      \"schlimm\"\r\n    ]\r\n  },\r\n  \"definitions\": {\r\n    \"adjective\": [\r\n      \"full of danger or uncertainty; precarious.\"\r\n    ],\r\n    \"adverb\": [\r\n      \"greatly or excessively.\"\r\n    ]\r\n  },\r\n  \"examples\": [\r\n    \"And how do you sap the energy of the insurgency when the parlous state of the economy keeps everyone desperately poor?\",\r\n    \"Finally, I want to talk quite seriously about the parlous state of politics in this House.\",\r\n    \"Is the state of American political fiction really so parlous perilous?\"\r\n  ]\r\n}\r\n\r\n```\r\nThe list of all available languages is available [here](https://github.com/FreddieDeWitt/extended-google-translate-api/blob/master/languages.js). Use 'auto' as a source language to use Google's language detection.\r\n\r\n\r\nOr you can disable examples using [`dataOptions`](#dataoptions-object) object:\r\n\r\n``` js\r\n\r\ntranslate(\"dog\", \"en\", \"de\", {examples: false}).then((res) =\u003e {\r\n    console.log(JSON.stringify(res, undefined, 2));\r\n}).catch(console.log);\r\n\r\n```\r\n\r\n\r\nWhich yields:\r\n\r\n``` json\r\n\r\n{\r\n  \"word\": \"dog\",\r\n  \"translation\": \"Hund\",\r\n  \"wordTranscription\": \"dôg\",\r\n  \"translationTranscription\": null,\r\n  \"translations\": {\r\n    \"noun\": [\r\n      \"Hund\",\r\n      \"Rüde\",\r\n      \"Pleite\"\r\n    ]\r\n  },\r\n  \"definitions\": {\r\n    \"noun\": [\r\n      \"a domesticated carnivorous mammal that typically has a long snout, an acute sense of smell, and a barking, howling, or whining voice. It is widely kept as a pet or for work or field sports.\",\r\n      \"a person regarded as unpleasant, contemptible, or wicked (used as a term of abuse).\"\r\n    ],\r\n    \"verb\": [\r\n      \"follow (someone or their movements) closely and persistently.\",\r\n      \"act lazily; fail to try one's hardest.\"\r\n    ]\r\n  }\r\n}\r\n\r\n```\r\n\r\n## API\r\n\r\n\r\n### translate(text, sourceLang, destLang, dataOptions)\r\n\r\n#### Arguments\r\n\r\n- `text`: `String` - text to be translated (if you want to get detailed translations and definitions it usually should be a single word)  \r\n- `sourceLang`, `destLang`: `String` - ISO code of source and desired languages of your text. Full list is [here](https://github.com/FreddieDeWitt/extended-google-translate-api/blob/master/languages.js).  \r\n- `dataOptions`: `Object` - see [here](#dataoptions-object). If you pass wrong fields to the dataOptions object, the program generates a warning.\r\n\r\n#### Response\r\n\r\nreturns Promise that:\r\n- resolves with `Response Object` (Take a look at [`Response Object`](#response-object))  \r\n- or rejects with Error (when request to translate.google.com failed) that have the following properties:\r\n  - message - an Error message\r\n  - statusCode - status code of the bad request\r\n\r\n\r\n### dataOptions Object\r\n\r\n#### Fields\r\n\r\n- `returnRawResponse`: Boolean - if this flag is chosen, then the [Result Object](#result-object) will be the raw data from request to translate.google.com.\r\n- `detailedTranslations`: Boolean\r\n- `definitionSynonyms`: Boolean - synonyms that are available for each of the definitions. Set this field to true if you want to get them.\r\n- `detailedTranslationsSynonyms`: Boolean - almost each detailed translation contains synonyms.  Set this field to true if you want to get them.\r\n- `definitions`: Boolean\r\n- `definitionExamples`: Boolean - almost each definition contains example(s). Set this field to true if you want to get them.\r\n- `examples`: Boolean\r\n- `removeStyles`: Boolean - google translate returns the word examples with the word surrounded by `\u003cb\u003e`, `\u003c/b\u003e`. Setting `removeStyles` to true removes all HTML styles from the examples.\r\n\r\n#### Defaults\r\n\r\n``` javascript\r\n\r\ndefaultDataOptions = {\r\n    returnRawResponse: false,\r\n    detailedTranslations: true,\r\n    definitionSynonyms: false,\r\n    detailedTranslationsSynonyms: false,\r\n    definitions: true,\r\n    definitionExamples: false,\r\n    examples: true,\r\n    removeStyles: true\r\n}\r\n```\r\n\r\nYou can always change defaults like this:  \r\n\r\n``` javascript\r\n\r\nconst translate = require('extended-google-translate-api');\r\ntranslate.defaultDataOptions.definitions = true;\r\n\r\n```\r\n\r\n### Response Object\r\n\r\nif (`dataOptions.returnRawResponse === true`) then the result will be the raw data from request to translate.google.com.\r\n\r\nOtherwise:\r\n\r\nThis object always contains the following fields:\r\n- `word`: String - the word itself\r\n- `translation`: String - Google Translate primary translation\r\n- `wordTranscription`: String - the transcription of the word\r\n- `translationTranscription`: String - the transcription of the main translation\r\n\r\nAvailability of other fields depends on [`dataOptions` Object](#dataoptions-object), the third argument of `translate` function\r\n\r\n- `dataOption.detailedTranslations === true`  \r\n\r\n  **Field**: `translations`: Object  \r\n  The keys of this object are word types (e.g. `noun`, `verb` etc.).  \r\n  Each key contains an array of translations (`String`) or if `dataOption.detailedTranslationsSynonyms === true` - an array of the following Objects  \r\n  - `translation`: String\r\n  - `synonyms`: [String]\r\n  - `frequency`: Number - the frequency of this translation (1, 2, 3). 1 means the most frequently, 3 - the least frequent words.\r\n\r\n  **Examples:** (some results was omitted for the sake of simplicity)  \r\n  - `dataOption.detailedTranslationsSynonyms === false`  \r\n\r\n  ``` json\r\n\r\n  \"translations\": {\r\n      \"noun\": [\r\n        \"Hund\",\r\n        \"Rüde\",\r\n      ]\r\n\r\n  ```\r\n\r\n  - `dataOption.detailedTranslationsSynonyms === true`  \r\n\r\n  ``` json\r\n\r\n  \"translations\": {\r\n      \"noun\": [\r\n        {\r\n          \"translation\": \"Hund\",\r\n          \"synonyms\": [\r\n            \"dog\",\r\n            \"hound\"\r\n          ],\r\n          \"frequency\": 1\r\n        },\r\n        {\r\n          \"translation\": \"Rüde\",\r\n          \"synonyms\": [\r\n            \"male\",\r\n            \"dog\"\r\n          ],\r\n          \"frequency\": 3\r\n        }\r\n      ]\r\n    }\r\n\r\n  ```\r\n\r\n- `dataObject.definitions === true`  \r\n  **Field:** `definitions`: Object  \r\n  The keys of this object are word types (e.g. `noun`, `verb` etc.).  \r\n  Each key contains an array of definitions (`String`) or if `dataOptions.definitionExamples === true` - an array of the following objects:  \r\n  - `definition`: String\r\n  - `example`: String  \r\n  Setting `dataOptions.definitionExamples === true` also adds the `synonyms` field to the object.\r\n  `synonyms` field is an object, the keys of which denote the type of the synonyms. The regular ones are stored under the key `normal`, some other possible tags are for instance `informal`, `formal`. The synonyms of each type are store in a string array.\r\n  **Examples:**  \r\n  - `dataOptions.definitionExamples === true`\r\n\r\n  ``` json\r\n\r\n  \"definitions\": {\r\n    \"noun\": [\r\n      \"a domesticated carnivorous mammal that typically has a long snout, an acute sense of smell, and a barking, howling, or whining voice. It is widely kept as a pet or for work or field sports.\",\r\n      \"a person regarded as unpleasant, contemptible, or wicked (used as a term of abuse).\",\r\n    ],\r\n    \"verb\": [\r\n      \"follow (someone or their movements) closely and persistently.\",\r\n      \"act lazily; fail to try one's hardest.\",\r\n    ]\r\n  }\r\n\r\n  ```\r\n  - `dataOptions.definitionExamples === false`  \r\n\r\n  ``` json\r\n\r\n  \"definitions\": {\r\n    \"noun\": [\r\n      {\r\n        \"definition\": \"a domesticated carnivorous mammal that typically has a long snout, an acute sense of smell, and a barking, howling, or whining voice. It is widely kept as a pet or for work or field sports.\",\r\n        \"example\": \"Shouts mingle with the barking and howling of dogs .\"\r\n      },\r\n      {\r\n        \"definition\": \"a person regarded as unpleasant, contemptible, or wicked (used as a term of abuse).\",\r\n        \"example\": \"come out, Michael, you dog!\"\r\n      }\r\n    ],\r\n    \"verb\": [\r\n      {\r\n        \"definition\": \"follow (someone or their movements) closely and persistently.\",\r\n        \"example\": \"photographers seemed to dog her every step\"\r\n      },\r\n      {\r\n        \"definition\": \"act lazily; fail to try one's hardest.\",\r\n        \"example\": \"He entered the season with a reputation for dogging it when he wasn't the primary receiver.\"\r\n      }\r\n    ]\r\n  }\r\n\r\n  ```\r\n`dataOptions.definitionSynonyms === true`\r\n  ``` json\r\n  \"definitions\": {\r\n    \"noun\": [\r\n      {\r\n        \"definition\": \"a domesticated carnivorous mammal that typically has a long snout, an acute sense of smell, nonretractable claws, and a barking, howling, or whining voice.\",\r\n        \"synonyms\": {\r\n          \"normal\": [\r\n            \"canine\",\r\n            \"hound\"\r\n          ],\r\n          \"informal\": [\r\n            \"doggy\",\r\n            \"pooch\",\r\n            \"mutt\"\r\n          ]\r\n        }\r\n      },\r\n      {\r\n        \"definition\": \"a mechanical device for gripping.\"\r\n      },\r\n      {\r\n        \"definition\": \"short for firedog.\"\r\n      }\r\n    ],\r\n    \"verb\": [\r\n      {\r\n        \"definition\": \"follow (someone or their movements) closely and persistently.\",\r\n        \"example\": \"photographers seemed to dog her every step\",\r\n        \"synonyms\": {\r\n          \"normal\": [\r\n            \"pursue\",\r\n            \"follow\",\r\n            \"stalk\",\r\n            \"track\",\r\n            \"haunt\"\r\n          ],\r\n          \"informal\": [\r\n            \"tail\"\r\n          ]\r\n        }\r\n      }\r\n    ]\r\n  }\r\n  ```\r\n- `dataOptions.examples === true`  \r\n  **Field:** `examples`: [String]  \r\n  The array contains all examples for the word.  \r\n  if `dataOptions.removeStyles === false` then the word will be surrounded by `\u003cb\u003e`, `\u003c\\b\u003e`  \r\n  **Examples:**  \r\n  - `dataOptions.removeStyles === true`\r\n\r\n  ``` json\r\n\r\n  \"examples\": [\r\n    \"One of the great mysteries of Australian political life is why a man who is about to dump a dog of a tax system on an unsuspecting public should appear so smug?\",\r\n    \"In order to get him to commit you have to treat him like a dog .\",\r\n    \"It is a dog of a day, relentless rain and biting cold fraying the nerve ends of men who like to be in perpetual motion.\",\r\n    \"During the Second World War, he treated Sinclair like a dog .\",\r\n    \"a dog fox\"\r\n  ]\r\n\r\n  ```\r\n\r\n  - `dataOptions.removeStyles === false`  \r\n\r\n  ``` json\r\n\r\n    \"examples\": [\r\n        \"One of the great mysteries of Australian political life is why a man who is about to dump a \u003cb\u003edog\u003c/b\u003e of a tax system on an unsuspecting public should appear so smug?\",\r\n        \"In order to get him to commit you have to treat him like a \u003cb\u003edog\u003c/b\u003e .\",\r\n        \"It is a \u003cb\u003edog\u003c/b\u003e of a day, relentless rain and biting cold fraying the nerve ends of men who like to be in perpetual motion.\",\r\n        \"During the Second World War, he treated Sinclair like a \u003cb\u003edog\u003c/b\u003e .\",\r\n        \"a \u003cb\u003edog\u003c/b\u003e fox\"\r\n    ]\r\n\r\n  ```\r\n  \r\n## Contacts\r\n\r\nIf you see a mistake in README, have a question or encountered a problem - please open an issue [here](https://github.com/FreddieDeWitt/extended-google-translate-api/issues) or write me at freddie.dewitt@yandex.com","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFreddieDeWitt%2Fgoogle-translate-extended-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFreddieDeWitt%2Fgoogle-translate-extended-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFreddieDeWitt%2Fgoogle-translate-extended-api/lists"}