Lookup API

關於訊息翻譯的討論衍生出兩個主要問題:

  1. [Lookup] 服務的「具體」介面如何以程式設計師選擇的語言呈現?接著
  2. 翻譯如何使我的程式能夠使用?

我們將根據這些意見回答。

查詢 API

Lookup API 程式庫可用於取得翻譯的字串。以下提供 C++ 中 Lookup API 的簡化檢視畫面:

class Lookup {
public:
  enum class Status {
    // No error.
    OK = 0,
    // The resource was unavailable as requested.
    UNAVAILABLE = 1,
  };
  static fpromise::result<std::unique_ptr<Lookup>, Lookup::Status>
    New(const std::vector<std::string>& locale_ids);
  fpromise::result<std::string_view, Lookup::Status> String(uint64_t message_id);
};

目前 Lookup API 僅限 C++ API。目前概念上只要擴充程式語言來支援其他語言,沒有任何概念問題。

實際的 API 可在 lookup.h 檔案中看到,基本上與上圖相同,只是其中包含說明文件、建構和測試負擔。撰寫本文時,只能使用高階 C++ API。我們也會視需要增加其他語言的高階 API。低階 C API 可做為使用其他語言,將 FFI 繫結寫入此功能的基礎。作為特殊情況,rust 不需要 FFI 繫結,因為低階實作採用 Rust 且可直接使用介面,但實際上尚未設定實際的 Rust API。

Lookup API 的基本用法如下所示:

std::vector<std::string> locale_ids = {"nl-NL"};
auto result = Lookup::New(locale_ids);
if (result.is_error()) {
  return;
}
auto lookup = result.value();
auto lookup_result = lookup.string(42);
if (lookup_result.is_error()) {
  // handle error
  return;
}
std::string_view message = lookup_result.value();
// Use `message`.

範例取自 lookup.h 說明文件。瞭解 API 後,這個範例相當簡單明瞭,只儲存一個項目:呼叫 lookup.string(...) 會使用神奇的數字 42 查詢訊息。身為程式設計師,可以詢問這組電話號碼的來源。下個章節將解答這個問題。