在本教程中，你将学习如何……

• 使用本地化API令牌
• 使用Lokalise API上传翻译文件
• 下载带有Lokalise API的翻译文件
• 实现OAuth 2流
• 列出客户项目
• 代表客户上传/下载翻译文件

你可以找到源代码在GitHub。

先决条件

本指南假设您已经创建了一个Lokalise项目(如果没有，在本指南中学习如何创建一个新项目）.在本教程中，我们将上传英文翻译。因此，请确保您的项目已将英语语言添加到在ISO代码。

如果您想在您的计算机上本地遵循本指南，您需要安装以下软件:

• Ruby 2.7或以上
• Rails 6或以上
• 您最喜欢的代码编辑器

我们要建造什么

在本教程的第一部分，我们将创建一个简单的Rails应用程序，它将上传英语翻译文件到您的Lokalise项目并将其下载回来。

在第二部分，我们将实现一个OAuth 2流，并代表用户向他们的项目上传和下载翻译文件。

准备一个新的Rails应用程序

运行以下命令创建一个新的Rails应用程序:

rails新的LokaliseApiDemo

这将为您创建一个应用程序框架。

让我们添加两个新文件:

• app / controllers / downloads_controller.rb
• app / controllers / uploads_controller.rb

打开配置/ routes.rb文件和调整它在以下方式:

资源:下载，仅%i[新创建]资源:上传，仅%i[新创建]

安装依赖关系

打开你的Gemfile并在其中添加新的宝石，像这样:

宝石ruby-lokalise-api, ~ > 6.0的宝石“dotenv-rails”、“~ > 2.7”宝石“rubyzip”、“~ > 2.3”

• ruby-lokalise-api是我们的官方API客户端
• Dotenv-rails将用于安全地存储环境变量
• rubyzip将用于读取ZIP文件

然后运行:

包安装

安装新添加的依赖项。

添加翻译文件

接下来，继续到配置/地区目录，并打开en.yml文件。该文件包含应用程序的英文翻译。让我们在其中创建四个翻译键:

en: upload_title:上传翻译文件upload_btn:上传!download_title:下载翻译文件download_btn:下载!

使用API令牌

获取API令牌以使用本地化API

创建一个.env文件放到项目的根目录中，并添加本地化API令牌。确保为您的Lokalise项目添加具有读写访问权限的API令牌。了解如何获取本地化API令牌。

LOKALISE_API_KEY = 123 secret456

❗️

永远不要公开暴露你的API密钥!

具体来说，不要忘记添加.env文件.gitignore。

初始化客户端

接下来,打开uploads_controller.rb中加载Ruby SDK，并初始化API客户端创建行动:

要求'ruby_lokalise_api'类UploadsController < ApplicationController def new end def create client = rubylokalise_api。client ENV['LOKALISE_API_KEY'] end end

获取您的本地化项目ID

中添加一个新的环境变量.env文件与您的Lokalise项目ID。了解如何获取Lokalise项目ID。

abc LOKALISE_PROJECT_ID = 123.

我们现在可以在视图/上传/ new.html.erb文件:

<标题> < % = t ' upload_title ' % > < / h1 > < % = button_to t(“upload_btn”),uploads_path % >

上传翻译文件到您的本地化项目

让我们编写一个简单的脚本来上传en.yml文件到您的本地化项目。请注意，它的内容必须是Base64编码。

defcreate client = RubyLokaliseApi。client ENV['LOKALISE_API_KEY'] file_content =文件。读“# {Rails.root} / config /地区/ en。yml”客户。upload_file ENV['LOKALISE_PROJECT_ID']， data: Base64.strict_encode64(file_content.strip)， filename: "en. "lang_iso: "en" redirect_to new_upload_path end

现在一切都准备好了，您可以通过运行以下命令来启动服务器:

rails的年代

然后打开浏览器，继续进行http://localhost:3000/uploads/new，然后点击“上传!”按钮。几秒钟后，您的翻译文件应该上传到Lokalise。

继续进入Lokalise，打开新创建的项目，并确保翻译键存在于编辑器中:

伟大的工作!

从Lokalise项目下载翻译文件

下载过程稍微复杂一些，因为我们必须处理ZIP归档文件。首先，让我们调整视图视图/下载/ new.html.erb：

<标题> < % = t ' download_title ' % > < / h1 > < % = button_to t(“download_btn”),downloads_path % >

现在调整downloads_controller.rb：

要求'ruby_lokalise_api'要求'open-uri'要求'zip'类DownloadsController < ApplicationController def new;end def create client = RubyLokaliseApi。client ENV['LOKALISE_API_KEY'] zip_file = client。download_files(ENV['LOKALISE_PROJECT_ID']， format: 'yaml'， placeholder_format::icu, yaml_include_root: true, original_filename: true, directory_prefix: "，缩进:'2sp'， filter_langs: %w[en])['bundle_url'] open_and_process zip_file redirect_to new_download_path end end

我们正在下载YAML格式的英文翻译文件。当然，您可以进一步调整下载选项:例如，如果您排除filter_langs所有语言的翻译都将包含在下载包中。

代码open_and_process私有方法:

类DownloadsController < ApplicationController #…private def open_and_process(path) Zip::File.open_buffer(open_remote(path)) do | Zip | Zip。每个做|entry| next，除非entry.name == 'en。Yml ' process_zip(entry) end end end end

只要我们想下载一个翻译文件，我们就比较entry.name与“en.yml”字符串。您可以进一步调整此条件以选择您感兴趣的所有文件。

最后，添加打开存档并处理其内容的方法:

类DownloadsController < ApplicationController #…private def open_remote(path) parsed_path = URI.parse(path) parsed_path。open end def process_zip(entry) data = YAML.safe_load(entry.get_input_stream.read) File.open(File.join(Rails. join))root， 'config'， 'locale '， entry.name)， 'w+:UTF-8') do |f| f.write data。To_yaml end end end

中的现有内容进行重写配置/地区/ en.yml文件中包含从localise获取的内容。

您现有的翻译将被覆盖!

控件中的任何翻译都将被当前实现覆盖en.yml和新的一起归档。如果您不希望发生这种情况，请将新翻译保存到另一个名称的文件中。例如，你可以这样写File.join (Rails。Root， 'config'， 'locale '， ' updated_#{entry.name})

现在您可以调整本地化翻译，您认为合适，继续http://localhost:3000/downloads/new，单击“下载!”按钮，并确保您的翻译文件已相应更新。例如，您可以尝试修改download_title翻译键，并确保标题在你按下“下载!”按钮后相应地更新。

使用OAuth 2流

注册一个OAuth 2应用

要开始，请联系我们的技术支持，让他们为你注册一个OAuth 2应用程序(如果你还没有注册)。您将看到我们将在接下来的步骤中使用的localise客户端ID和客户端密钥。

你可以把这些钥匙存储在.env文件:

OAUTH2_CLIENT_ID = your_id OAUTH2_CLIENT_SECRET = your_secret

❗️

永远不要公开暴露您的OAuth 2客户端秘密!

具体来说，不要忘记添加.env文件.gitignore。

实现OAuth 2流

让我们创建一个新的oauth2_flows_controller.rb内容如下:

require 'ruby_lokalise_api'类Oauth2FlowsController < ApplicationController def new @auth_url = auth_client. xmlauth scope: %(read_projects read_files write_files)， redirect_uri: 'http://localhost:3000/oauth2_flows/callback'， state: rand(10000) end private def auth_client RubyLokaliseApi. netauth_client ENV['OAUTH2_CLIENT_ID']， ENV['OAUTH2_CLIENT_SECRET'] end end

在新操作时，我们将生成一个特殊的认证URL，您的客户必须访问该URL才能通过Lokalise登录并获得一个特殊的令牌。我们需要这个令牌代表客户行事。

的范围属性包含您希望从客户请求的权限数组。只要我们想获取客户项目列表并管理翻译文件，我们将提供三个作用域。

的redirect_uri在授予所请求的访问权限后，客户将被重定向到的位置。

状态是防止CSRF攻击的随机字符序列。

现在我们来实现回调客户通过Lokalise登录后将登陆的操作:

类Oauth2FlowsController < ApplicationController #…Def回调响应= auth_client。令牌params[:代码)session[:lokalise_token] = response['access_token'] session[:lokalise_refresh] = response['refresh_token'] redirect_to new_oauth2_flow_path end end

params[:代码)是lockalise会为你生成的密码。通过调用令牌方法以及代码，您正在请求OAuth 2访问令牌以及刷新令牌。访问令牌用于代表用户行事，但它具有有限的生命周期(通常为3600秒;这个值可以用反应(“expires_in”)）.令牌过期后，您可以使用refresh令牌对其进行刷新:Response = auth_client。刷新“YOUR_REFRESH_TOKEN”。的反应(“access_token”)将包含一个新的令牌。

我们将这两个令牌存储在会话中，并将用户重定向回新行动。

最后，我们可以添加一个动作来清除令牌和选中的项目(我们稍后会讲到):

类Oauth2FlowsController < ApplicationController #…Def log_out session.delete:lokalise_token session.delete:lokalise_refresh session.delete:lokalise_project_id redirect_to new_oauth2_flow_path end结束

在这一点上，我们可以打开视图/ oauth2_flows / new.html.erb并提供一个简约的标记:

OAuth 2 flow
 <% if session[:lokalise_token].present?% >你OAuth 2牌:会话(lokalise_token): < % = % > < br >你OAuth 2刷新令牌:会话(lokalise_refresh): < % = % > < br > Lokalise项目id:会话(lokalise_project_id): < % = % > < br > < % = link_to“选择一个项目来处理的,projects_path % > < br > < % = link_to“上传文件”,new_upload_path % > < br > < % = link_to“下载文件”,new_download_path % > < br > < br > < % = link_to“注销”,log_out_oauth2_flows_path % >其他< % % > < % = link_to登录通过Lokalise, @auth_url % > < % % >结束

选择一个工作项目

下一步是允许客户选择他们想要与之交互的项目。因此，创建一个新的projects_controller.rb：

要求'ruby_lokalise_api'类ProjectsController < ApplicationController before_action:check_token def index客户端= rubylokalise_api。Oauth2_client session[:lokalise_token] @projects = client。(限额:5000).collection项目。Map {|p| {id: p.p project_id, name: p.p name}} end def选择session[:lokalise_project_id] = params[:project_id] redirect_to new_oauth2_flow_path end end

在指数操作中，我们使用客户的访问令牌获取所有项目并提取它们的id和名称。

的选择action用于实际选择一个项目并将其ID存储在会话中。

我们也打开application_controller.rb并添加两种方法:

类ApplicationController < ActionController::Base private def check_token redirect_to new_oauth2_flow_path除非会话[:lokalise_token].present?结束def check_project_id redirect_to new_oauth2_flow_path除非session[:lokalise_project_id].present?结束结束

我们将使用这些来检查客户是否已经通过Lokalise登录并选择了一个项目。

最后，打开视图/项目/ index.html.erb并添加以下标记:

选择要使用的项目
 
 <% @projects。each do |project| %> 
 <%= button_to project[:name]， choose_projects_path(project_id: project[:id]) %> id: <%= project[:id] %> <% if session[:lokalise_project_id] == project[:id] %>(当前选中)<% end %> 
 <% end %> 

我们简单地显示所有项目的列表，并使用按钮选择其中一个项目。稍后，客户可以返回此页面并根据需要选择另一个项目。

设置路由

让我们将所有必要的路由添加到配置/ routes.rb文件:

#……资源:oauth2_flows, only: %i[new] do collection do get 'callback' get 'log_out' end end end资源:projects, only: %i[index] do collection do post 'choose' end end root 'oauth2_flows#new'

代表用户上传翻译文件

代表用户上传文件的过程非常类似于我们对常规API令牌做了什么。事实上，唯一的区别是如何实例化客户端和提供项目ID。之前我们写道:

客户端= RubyLokaliseApi。client ENV['LOKALISE_API_KEY'] client。Upload_file session[:lokalise_project_id] #…

现在我们应该用oauth2_client方法，并从会话存储中获取项目ID:

客户端= RubyLokaliseApi。oauth2_clientsession[:lokalise_token] client.upload_file session[:lokalise_project_id], data: Base64.strict_encode64(file_content.strip), filename: 'en.yml', lang_iso: 'en'

以下是“uploads”控制器的完整代码(注意“before actions”的用法):

类UploadsController < ApplicationController before_action:check_token before_action:check_project_id def new;end def create client = RubyLokaliseApi。oauth2_clientsession[:lokalise_token] file_content = File.read "#{Rails.root}/config/locales/en.yml" client.upload_file session[:lokalise_project_id], data: Base64.strict_encode64(file_content.strip), filename: 'en.yml', lang_iso: 'en' redirect_to new_upload_path end end

代表用户下载翻译文件

下载文件的过程与我们用普通的代币做了什么。唯一的区别是如何实例化客户端并提供项目ID。以下是“downloads”控制器的完整代码:

DownloadsController < ApplicationController before_action:check_token before_action:check_project_id def new;end def create client = RubyLokaliseApi。oauth2_clientsession[:lokalise_token] zip_file = client.download_files(session[:lokalise_project_id], format: 'yaml', placeholder_format: :icu, yaml_include_root: true, original_filenames: true, directory_prefix: '', indentation: '2sp', filter_langs: %w[en])['bundle_url'] open_and_process zip_file redirect_to new_download_path end private def open_and_process(path) Zip::File.open_buffer(open_remote(path)) do |zip| zip.each do |entry| next unless entry.name == 'en.yml' process_zip(entry) end end end def open_remote(path) parsed_path = URI.parse(path) parsed_path.open end def process_zip(entry) data = YAML.safe_load(entry.get_input_stream.read) File.open(File.join(Rails.root, 'config', 'locales', entry.name), 'w+:UTF-8') do |f| f.write data.to_yaml end end end

进行测试

继续http://localhost:3000/oauth2_flows/new，并按“本地登入”。你将被导航到localise，并被要求为你的应用程序授予必要的权限:

点击“允许访问”。你会被导航回你的应用。

接下来，单击“Choose a project to work with”，并选择其中一个项目。

最后，点击“上传文件”或“下载文件”，与之前一样进行上传/下载过程。确保你的翻译得到相应的更新。

就这样，干得好!