Any chance for an API?

[MMoMM-org]

I would like to pass a word, source language, target language to the api and get back the translated word.

Probably the return value needs to be an array with the translation word and perhaps the descriptions of it.

Would that be possible?

[Fevol]

It is absolutely possible: in the current version, you can access the currently active translator API using const translator = app.plugins.plugins['translate']?.translator. This translator implements the API of the service that the user selected in the General settings:

There is a little bit of documentation on how you can use the API (see here), but I realize I don't have a lot of examples (and it is rather out-of-date), so here's a specific example of how you could access the API and get translations:

const translator = app.plugins.plugins['translate']?.translator
// Make sure to check whether translator is defined
const translation_response = await translator.translate(TEXT, FROM, TO, APPLY_GLOSSARY)
if (translation_response.status_code == 200) {
  const translated_term = translation_response.output 
  // Do something with the translated term/sentence
} else {
  // If translation API encounters errors, make sure to display it to the user 
  console.error(translation_response.message)
}

Where text is just a regular string, from and to are ISO 639-1 codes and apply_glossary determines whether the users glossary should be applied to the input text. You can also provide "auto" to from, for automatically detecting the source language.

Make sure to take a look at lingva-translate.ts (or any of the other service implementations) too. They'll give you a good idea on what the API returns.

---

Probably the return value needs to be an array with the translation word and perhaps the descriptions of it.

I'd really like to be able to provide this too, but sadly, there is currently only one translation service that offers descriptions for a translation, and that is LingvaTranslate (and perhaps Fanyi Baidu/... too). So for now, this output is not returned in the API.

However, you might be able to phibro0's obsidian-dictionary plugin to get term descriptions:

const translated_term = 'SOMETHING';
const dictionary_plugin = app.plugins.plugins['obsidian-dictionary-plugin']?.manager
if (dictionary_plugin) {
  const descriptions = dictionary_plugin.requestDefinitions(translated_term);
  if (descriptions) {
    // Do something with the word descriptions
  }
}

Though I believe that the dictionary_plugin will only look up the term in the language that the user has specified in the settings, so that approach might not work.

In the future, I may make my own plugin for getting synonyms/descriptions/etc.. using any available API, obsidian-dictionary plugin already does a lot, but I'd need to have a more rigid API in order to get the functionaity I want for the translate plugin. Currently, I don't really have the time to work on it, so it wouldn't be finished by February, at the earliest.

[Fevol]

Hey @MMoMM-org, does this solve your issue? I'd be glad to help you further/improve upon the API docs wherever possible.

[MMoMM-org]

Hi, thanks that helps a lot.
And I noticed that I was tackling it wrong, I need to figure out how to get into a dictionary for my specific ask as I want to translate just one word... which can have several meanings.

You plugin is more for full sentences.

But nevertheless:

1. the code above helped a lot
2. would be cool if you could in the future write an api which wraps around the different implementations and handles errors in itself
3. as you probably close this issue I would suggest to get this information into the documentation, could be helpful to others.

And thanks again for writing this up, this helped a lot.

[Fevol]

I need to figure out how to get into a dictionary for my specific ask as I want to translate just one word... which can have several meanings. (...) You plugin is more for full sentences.

That's true, I'll be trying to get some sort of dictionary integration going for the future which should give better translations for single words/terms, but as mentioned before, that's going to be a little ways off.

---

2. would be cool if you could in the future write an api which wraps around the different implementations and handles errors in itself

The API does handle all internal errors, but when you make a request, it isn't guaranteed that you get back a translation (due to service being offline, invalid authentication info, ...). So that's why I'm checking status_code === 200 in the example I gave; if any error had occurred, then you'd get a status code ≠ 200, and an (error) message will be provided in the return values.

The reason why the message isn't automatically displayed, is so that people can decide what to do with it: completely ignoring it, throwing an error, putting it in console log, making a notice in Obsidian, etc..

Basically what I'm saying is, it's perfectly fine to just use the code below, but you will not know if/how the translation failed.

// If an error occurs during translation, translated_text = undefined
const translated_text = await translator.translate(TEXT, FROM, TO, APPLY_GLOSSARY).translation

---

3. as you probably close this issue I would suggest to get this information into the documentation, could be helpful to others.

Don't worry, I won't be closing the issue till we're both satisfied! I've added a brief API documentation here, for everyone that needs it. If you have any suggestions on how I could improve it, please let me know!