Supply Translations to your Flutter app.

为您的Flutter应用提供翻译。

When it comes to “Internation-­alizing” your Flutter app, there’s a few things you have to set up first before you can proceed as it’s stated in the documentation, Setting up an internationalized app:

当涉及“国际化” Flutter应用程序时，必须首先进行一些设置，然后才能按照文档“ 设置国际化应用程序”中的说明进行操作 ：

“To add support for other languages, an application must…include a separate package called flutter_localizations.… If you want your app to work smoothly on iOS then you have to add the package ‘flutter_cupertino_localizations’”

“要增加对其他语言的支持，应用程序必须…包含一个单独的名为flutter_localizations的软件包。…如果您希望您的应用程序在iOS上正常运行，则必须添加软件包'flutter_cupertino_localizations'”

With that, you can then import the flutter_localizations library. Next, you must specify the ‘localizationsDelegates’ and ‘supportedLocales’ to the widget, MaterialApp. Each delegate encapsulates a collection of localized values or, with regards to this article, text translations.

这样，您就可以导入flutter_localizations库。 接下来，您必须为小部件MaterialApp指定“ localizationsDelegates”和“ supportedLocales”。 每个委托封装一个本地化值的集合，或者就本文而言，封装文本翻译。

Flutter has a process to provide such translations (localization strings), but I preferred Thomas Ecalle’s own library, FlappyTranslator, as it too provided a means to display native text strings and their translated text strings in a Flutter app. His work inspired me to create the library package, I10n_Translator. One particular characteristic that I liked and blatantly adapted from his library to use in my own was, as he writes in his article, “our strings need to be stored in a human-readable and easy-to-use-or-update format for non-developers.”

Flutter有提供此类翻译( 本地化字符串 )的过程，但我更喜欢Thomas Ecalle自己的库FlappyTranslator ，因为它也提供了一种在Flutter应用程序中显示本机文本字符串及其翻译文本字符串的方法。 他的工作启发了我创建库包I10n_Translator 。 我喜欢和公然改编自他的图书馆到我自己用的一个特别的特点是，因为他在他的文章中写道，“我们的字符串需要存储在人类可读的 ， 易于使用的，或更新格式非开发人员。”

His library simply provided a text file that contains comma-separated values. This is commonly called a CSV file. It’s a text file that uses a comma to separate its text values, and is readily recognized by many editors and other popular programs. Thus allowing ‘non-developers’, for example, to easily enter the text translations for a Flutter app. And so, the library package, I10n_Translator, also uses a CSV file to store text translations.

他的库只提供了一个包含逗号分隔值的文本文件。 这通常称为CSV文件。 这是一个文本文件，使用逗号分隔其文本值，并且容易被许多编辑器和其他流行程序识别。 因此，例如，允许“非开发人员”轻松输入Flutter应用程序的文本翻译。 因此，库软件包I10n_Translator也使用CSV文件存储文本翻译。

As an example, below is a screenshot of the CSV file named, i10n.csv, containing some English words and their corresponding French and Spanish translations in the simple Windows text editor called, Notepad.

例如，下面是一个名为i10n.csv的CSV文件的屏幕快照，其中包含一些英语单词以及它们在简单的Windows文本编辑器Notepad中对应的法语和西班牙语翻译。

As you see below, this text file is easily read in by Microsoft Excel presenting its contents in a nice easy-to-read tabular format. You can see the English column, the French column, and the Spanish column. Further, you can see it’s the first line of text displayed that is the line that contains the ‘language codes’ (ISO 639–1) represented in this CSV file. Lastly, it also has blank lines here and there, again, for readability.

如下所示，Microsoft Excel可以轻松阅读此文本文件，并以易于阅读的表格格式显示其内容。 您可以看到英语列，法语列和西班牙语列。 此外，您可以看到显示的第一行文本是包含此CSV文件中表示的“语言代码”( ISO 639-1 )的行。 最后，为了方便阅读，它在各处也有空白行。

我喜欢截图。 单击要点。 (I Like Screenshots. Click For Gists.)

As always, I prefer using screenshots over gists to show concepts rather than just show code in my articles. I find them easier to work with frankly. However, you can click or tap on these screenshots to see the code they represent in a gist or in Github. Ironically, it’s better to read this article about mobile development on your computer than on your phone. Besides, we program on our computers — not on our phones. For now.

与往常一样，我更喜欢使用屏幕截图而不是要点来显示概念，而不是仅在文章中显示代码。 坦率地说，我发现它们更易于使用。 但是，您可以单击或点击这些屏幕截图，以查看它们在要点或Github中表示的代码。 具有讽刺意味的是，最好在计算机上阅读这篇文章，而不是在手机上阅读有关移动开发的文章。 此外，我们在计算机上编程，而不是在手机上编程。 目前。

社交媒体上没有动态图片 (No Moving Pictures On Social Media)

Further, there are a few gif files in this article demonstrating functions and features in ‘moving pictures.’ However, I’m told viewing such files is not possible when reading this article on platforms like Instagram, Facebook, etc. You’ll see empty square spaces where the gif files should be. Please, be aware of this. I would recommend reading this in a browser on medium.com.

此外，本文中有一些gif文件，展示了“运动图片”中的功能。 但是，我被告知在Instagram，Facebook等平台上阅读本文时，无法查看此类文件。您会在gif文件所在的地方看到空白的空格。 请注意这一点。 我建议在medium.com上的浏览器中阅读此内容。

Let’s begin.

让我们开始。

通过示例和示例应用程序学习 (Learn by Example and Sample App)

The CSV file named, i10n.csv, you see above is actually used by the sample app, Shrine MVC. This sample app, of course, is available to you on Github which you can download so to understand how this library package can be used in your own Flutter app. Note, the library package itself has its own example app as well to further demonstrate its implementation. The source code of the example app is also found on Github.

您在上面看到的名为i10n.csv的CSV文件实际上由示例应用程序Shrine MVC使用 。 当然，可以在Github上使用该示例应用程序，您可以下载该示例程序，以了解如何在自己的Flutter应用程序中使用此库包。 注意，库包本身也有自己的示例应用程序，以进一步演示其实现。 示例应用程序的源代码也在Github上找到。

生成您的翻译 (Generate Your Translations)

Below is a screenshot of the resulting code generated from the CSV file. Of course, if you’re familiar with my past library packages, you know I like options. In this case, you have the option to instead ‘read in’ the CSV file directly to provide the translations! You don’t have to generate this code from the CSV file if you don’t want to. I’ll explain that later on. For now, let’s see how you’d use this code anyway as there may be times when you’ll want to generate it.

以下是从CSV文件生成的结果代码的屏幕截图。 当然，如果您熟悉我过去的库软件包 ，就知道我喜欢选项。 在这种情况下，您可以选择直接直接读入CSV文件以提供翻译！ 如果不想，您不必从CSV文件生成此代码。 稍后再解释。 现在，让我们看看您将如何使用此代码，因为有时可能要生成它。

In the screenshot above, there’s now a Map object called, i10nWords, that contains all the translations currently available to the Flutter app. Below, is a screenshot of the sample app, Shrine MVC, taking in that object with an import statement and then supplying that object to the init() function in the i10n_translator library package. Easy peasy.

在上面的屏幕截图中，现在有一个名为i10nWords的Map对象，其中包含Flutter应用程序当前可用的所有翻译。 下面是示例应用程序Shrine MVC的屏幕截图，该应用程序使用import语句接收该对象，然后将该对象提供给i10n_translator库包中的init ()函数。 十分简单。

改变你的语言 (Change Your Language)

As it happens, when you run the sample app, Shrine MVC, you have the means to manually ‘switch’ between the default text and its two translations. There’s a menu option allowing you to do just that. The screenshots below depict the change, for example, from English to French. Notice the labels of the displayed articles then change accordingly.

碰巧的是，当您运行示例应用程序Shrine MVC时 ，您可以手动在默认文本及其两种翻译之间进行“切换”。 有一个菜单选项允许您执行此操作。 下面的屏幕快照描述了从英语到法语的更改。 注意显示文章的标签，然后相应地更改。

Below is the screenshot of the code that displays those items and subsequently they’re corresponding labels. You can see the default strings, in this case, are in English. However, note when looking at the list of Product objects below, the named parameters called, name, are not being supplied the strings directly but are instead being supplied the static function, s(), from the library package, i10n_translator. It’s in this static function where the translation is performed and returned to the named parameter, name.

下面是显示这些项目以及随后它们是对应标签的代码的屏幕截图。 在这种情况下，您可以看到默认字符串是英语。 但是，请注意，在查看下面的Product对象列表时，不会直接向字符串提供名为name的命名参数，而是从库包i10n_translator为其提供静态函数s ()。 在此静态函数中，将执行转换并返回到命名参数name 。

如图所示 (Shown In Pictures)

Below is a gif file demonstrating how the app’s text dynamically changes when you select a ‘language code’ in the menu popup. Note, instead of ‘language code’, I could have just as easily used flags or what have you. It didn’t have to be a list of language codes. Regardless, it’s the library package that takes in the language code and changes the Locale of the app accordingly.

以下是一个gif文件，演示了在菜单弹出窗口中选择“语言代码”时应用程序文本的动态变化。 注意，除了“语言代码”，我还可以使用同样容易使用的标志或您拥有的标志。 它不必是语言代码列表。 无论如何，都是库包接受了语言代码并相应地更改了应用程序的语言环境。

加载您的语言环境 (Load Your Locale)

The screenshot below conveys the PopupMenuButton widget with its three vertical dots displayed in the gif file above. Notice how the I10n_translator library package is called upon to load the selected Locale. Consequently, in the code, that value is then saved in the app’s system preferences so to load that selected locale if and when the app starts up again. Finally, the app’s interface is refreshed to present the new text translations.

下面的屏幕截图显示了PopupMenuButton小部件，其三个垂直点显示在上面的gif文件中。 注意如何调用I10n_translator库包以加载选定的语言环境。 因此，在代码中，该值随后被保存在应用程序的系统偏好设置中，以便在应用程序再次启动时以及何时启动时加载所选的语言环境。 最后，应用程序的界面将刷新以显示新的文本翻译。

Note, further along in the code, I could have read the generated object, i10nWords, and listed the ‘language codes’ it contained instead of just explicitly listing PopupMenuItems in the code, but I was lazy.

注意，在代码中，我可能已经读过生成的对象i10nWords并列出了其中包含的“语言代码”，而不是在代码中明确列出PopupMenuItems，但是我很懒。

Again, the idea behind all this is to provide the app’s translations in a simple text file delimited by commas. It assumes the ‘default’ language is found in the first column. You would then insert those text strings throughout the app itself as you normally would. However, instead of using the widget, Text, you would insert those text strings into the static functions, I10n.s() or I10n.t(). The first column then serves as the ‘key field’ when reading in this CSV file. Note, as a key field, the first column of text is therefore case-sensitive.

同样，所有这些操作背后的想法是在以逗号分隔的简单文本文件中提供应用程序的翻译。 假定在第一列中找到“默认”语言。 然后，您将像往常一样将这些文本字符串插入整个应用程序本身。 但是，您无需使用小部件Text ，而是将这些文本字符串插入静态函数I10n中。 s ()或I10n。 t ()。 然后，在读取此CSV文件时，第一列将用作“关键字段”。 注意，作为关键字段，文本的第一列因此区分大小写。

设置生成 (Set Up To Generate)

Once the translations are ready, you have the option now to generate the code and supply those translations to your Flutter app as a parameter. Note, to use this option, you have to set up one thing in your app’s pubspec.yaml file. Under the header, dev_dependencies, you have to reference the library package so you can call it within your chosen IDE.

翻译准备就绪后，您现在可以选择生成代码，并将这些翻译作为参数提供给Flutter应用程序。 请注意，要使用此选项，您必须在应用程序的pubspec.yaml文件中设置一件事。 在标题dev_dependencies下 ，您必须引用库包，以便可以在所选的IDE中调用它。

And so now using your IDE’s terminal window, for example, you’re free to type in the following command line to generate the code into a Dart file:

因此，例如，现在使用IDE的终端窗口，您可以自由键入以下命令行以将代码生成到Dart文件中：

flutter pub run i10n_translator test.csv path/destination/results.dart

flutter pub run i10n_translator test.csv path/destination/results.dart

The command line above, as an example, would read in a CSV file called, test.csv, and produce a Dart file called, results.dart, in the specified location. It will contain the Map object, i10nWords. Note, however, if you simply type out the command line without the two arguments, it assumes the following CSV file and resulting Dart file:

作为示例，以上命令行将在指定位置读取一个名为test.csv的CSV文件，并生成一个名为results.dart的Dart文件。 它将包含Map对象i10nWords 。 但是请注意，如果您只键入不带两个参数的命令行，它将假定以下CSV文件和生成的Dart文件：

flutter pub run i10n_translator [i10n.csv] [i10nwords.dart]

flutter pub run i10n_translator [i10n.csv] [i10nwords.dart]

Further still, however, if you’re innately lazy and don’t like typing like me, you could use Android Studio and create a ‘Dart command-line app’ that instead points directly to the library package file, i10n_translator.dart. You then just ‘run’ that configuration to produce the resulting Dart file. See below.

更进一步，但是，如果您天生懒惰并且不喜欢像我这样键入，则可以使用Android Studio并创建一个“ Dart命令行应用程序”，而直接指向库包文件i10n_translator.dart 。 然后，您只需“运行”该配置以生成最终的Dart文件。 见下文。

它是如何产生的？ (How Does It Generate?)

So, how does that command line work? Looking at a screenshot of that i10n_translator.dart file, you can see there’s a main() function in there that calls the library package class, I10nTranslator. Further, it supplies any arguments to the function, generate() that creates the code.

那么，该命令行如何工作？ 查看该i10n_translator.dart文件的屏幕截图，您可以看到其中有一个main ()函数调用库包类I10nTranslator 。 此外，它向函数提供任何参数，并生成创建代码的()。

只是CSV！ (Just The CSV!)

Again, I’m lazy. I don’t want to do that ‘extra step’ of generating the code to display the translations. I’ve got this CSV file now, why don’t I just use that file?? To do that, I’ll just call the init() function with no parameters.

同样，我很懒。 我不想执行生成代码以显示翻译的“额外步骤”。 我现在有这个CSV文件，为什么我不只是使用该文件？ 为此，我将只调用不带参数的init ()函数。

You see, I’ve simply included the text file as an asset in the Flutter app and have the library package read it in at start-up to supply the translations. By default, this library package will look for the CSV file in the assets directory under the location, assets/i10n/i10n.csv. And so, instead of adding the library package under the header, dev_dependences, I’ve specified that file location in the pubspec.yaml file. When the app starts up, that CSV file will be read in and the translations made available to the Flutter app. Easy peasy.

您会发现，我只是将文本文件作为资产包含在Flutter应用程序中，并在启动时就将库包读取其中以提供翻译。 默认情况下，此库程序包将在assets目录下的assets/i10n/i10n.csv下查找CSV文件。 因此，我没有在头文件dev_dependences下添加库包，而是在pubspec.yaml文件中指定了该文件位置。 应用启动时，将读取该CSV文件并将翻译提供给Flutter应用。 十分简单。

And so, over time for example, while you're developing your app, you may have more translations entered into that CSV file. There’s no need to generate any code from time to time. Merely place that file in the ‘assets’ location and you’re good to go!

因此，例如，随着时间的流逝，在开发应用程序时，可能会在该CSV文件中输入更多翻译。 无需不时生成任何代码。 只需将文件放在“资产”位置，就可以了！

一言不发 (No Words)

Now, what happens if there’s no translation available for a particular word in your Flutter app? Nothing happens. It simply displays the original key field — which happens to be the original text. See what I mean?

现在，如果Flutter应用中没有针对特定单词的翻译，该怎么办？ 没发生什么事。 它仅显示原始键字段-恰好是原始文本。 明白了吗？

This is a utility class, it’s not to hinder your own Flutter app. After all, it’s your Flutter app! An app, no doubt, designed for a very important task! It’s that task that is of primary concern. If there happens to be a ‘missing translation’, you certainly don’t want your app to blow up because of it! So it won’t. It’ll just display the string supplied to the static function I10n.s() or I10n.t().

这是一个实用程序类，并不是要阻止自己的Flutter应用程序。 毕竟，这是您的Flutter应用！ 毫无疑问，该应用程序是为一项非常重要的任务而设计的！ 首要任务是任务。 如果碰巧是“缺少翻译”，则您当然不希望因为它而使应用程序崩溃！ 所以不会。 它只会显示提供给静态函数I10n的字符串。 s ()或I10n。 t ()。

If you’ve implemented those static functions throughout your app and yet there’s no CSV file, for example, there’s no problem. Again, they’ll simply display the passed text string. Further, even if you mistakenly pass nothing to those static functions, an empty string is then displayed…unseen of course.

例如，如果您已在整个应用程序中实现了这些静态功能，但没有CSV文件，那就没有问题。 同样，它们将仅显示传递的文本字符串。 此外，即使您错误地将任何内容都没有传递给这些静态函数，也会显示一个空字符串……当然是看不见的。

迟到总比不到好 (Better Late Than Never)

Like documentation, translations tend not to get done as the development progresses in projects. Frankly, like documentation, it tends only to get done at the last minute! Again, the priority is getting the app working; not its translations. This library package allows for that. With their unique signature, you search your code and quickly find all the static functions and collect all the text that needs translating. Better yet, have the library package do that for you — but, I’ll explain that a litter later.

像文档一样，随着项目开发的进行，翻译往往不会完成。 坦白说，就像文档一样，它往往只能在最后一刻完成！ 同样，首要任务是使应用程序正常运行。 不是它的翻译。 这个库包允许这样做。 使用它们独特的签名，您可以搜索代码并快速找到所有静态函数，并收集所有需要翻译的文本。 更好的是，请图书馆书包为您做这件事-但是，我稍后再解释。

添加您的代表 (Add Your Delegates)

Like the sample app, Shrine MVC, the example included with the library package has to first pass the ‘supported locales’ and ‘localization delegates’ to the MaterialApp widget whenever a Flutter app requires translations. Again, this has to be done if you want to introduce Internationalization into your Flutter app — even without using the library package, i10n_translator. Both the entries, I10nDelegate()and I10n.supportedLocalesare supplied by the library package, i10n_translator.dart, and so it’ll take care of that part for you.

与示例应用程序Shrine MVC一样 ，库包中包含的示例必须在Flutter应用程序需要翻译时首先将“支持的语言环境”和“本地化委托”传递给MaterialApp小部件。 同样，如果您要在您的Flutter应用中引入国际化，即使没有使用库包i10n_translator ，也必须这样做。 I10nDelegate()和I10n.supportedLocales这两个条目都是由库包i10n_translator.dart提供的 ，因此它将为您提供帮助。

进行切换！ (Make The Switch!)

As it happens, its example code also has a menu option that allows you to switch between languages. In this case, between eight different locales. Once selected, like the first sample app, Shrine MVC, the code calls the library package to load the selected locale, it then saves that locale into system preferences, and then refreshes the UI. Note, the saving of the selected locale uses another library package of mine called, Prefs.

碰巧的是，其示例代码还具有一个菜单选项，可让您在语言之间进行切换。 在这种情况下，在八个不同的语言环境之间。 选择之后，就像第一个示例应用程序Shrine MVC一样 ，代码将调用库程序包以加载选定的语言环境，然后将其保存为系统偏好设置，然后刷新UI。 注意，保存所选语言环境使用的是我的另一个库包Prefs 。

等待CSV (Await The CSV)

The example also looks up the file, assets/i10n/i10n.csv, for its translations. Since reading a file in Flutter involves an asynchronous operation, that means it involves Future objects. Hence, the example, in this case, needs time to ‘read in’ the CSV file before it can proceed. As you see below, that’s why a FutureBuilder widget is used right away in the example.

该示例还查找文件assets/i10n/i10n.csv进行翻译。 由于在Flutter中读取文件涉及异步操作，因此这意味着它涉及Future对象。 因此，在这种情况下，该示例在继续进行之前需要时间来“读入” CSV文件。 如下所示，这就是在示例中立即使用FutureBuilder小部件的原因。

等不及了 (It Can’t Wait)

Now, as I suggested earlier, there will be instances where you don’t want to wait for a file to be read in. If you recall, it’s in those instances where you’ll want to generate that Map object called, i10nWords. For example, if a FutureBuilder widget is not to be used, the example code could look like this:

现在，正如我之前所建议的，在某些实例中，您不想等待文件被读入。回想一下，在某些实例中，您将要生成名为i10nWords的 Map对象。 例如，如果不使用FutureBuilder小部件，则示例代码如下所示：

After using the i10n_translator file to generate the code, the library package’s init() function is called like before, but now the generated code in the file, i10n_words.dart, is instead read in as a parameter. This, of course, is a much faster operation and yet produces the very same results as in the first version. Click on the example code’s menu option, and you can change the text to eight different languages in the good ol’ ‘counter starter app.’ Easy peasy.

使用i10n_translator文件生成代码后，将像以前一样调用库包的init ()函数，但现在将文件i10n_words.dart中生成的代码作为参数读取。 当然，这是一个更快的操作，但产生的结果与第一个版本中的结果完全相同。 单击示例代码的菜单选项，然后可以在“反启动程序”中将文本更改为八种不同的语言。 十分简单。

做一个列表 (Make A List)

I had hinted earlier that, ideally, while you’re developing your app, this library package should just collect all the text that needs translating for you and put it in that CSV file for your translators to work on later. Well, the library package does just that — almost. As you see in the screenshot below, the s() function does indeed ‘add’ the text string (the key) passed to it into a file when the app is running, but there’s a problem.

之前我曾暗示过，理想情况下，在您开发应用程序时，此库包应只收集需要翻译的所有文本，并将其放在该CSV文件中，以供您的翻译以后使用。 好吧，这个库包几乎就是那样。 如您在下面的屏幕快照中所见， s ()函数确实确实在应用程序运行时确实将传递给它的文本字符串(键)“添加”到了文件中，但是存在问题。

Like you, I still have a lot to learn from this wonderful tool that is Flutter. And so, as of writing, there’s a CSV file filling up with all this text, but I can’t figure out how to then readily gain access to. I would have liked to have resolved this before publishing this article, but...you know…I’m lazy.

像您一样，我仍然可以从Flutter这个很棒的工具中学到很多东西。 因此，在撰写本文时，有一个CSV文件填充了所有这些文本，但是我不知道该如何轻松获得访问权限。 我本来希望在发布本文之前解决此问题，但是...您知道...我很懒。

Please, if you’re up for it, let me know what would be the best approach to provide that file to the developer? Better yet, to a non-developer making the whole process of translating…you know…Easy peasy.

请支持，如果您愿意的话，请让我知道将文件提供给开发人员的最佳方法是什么？ 更好的是，对于非开发人员来说，要进行翻译的整个过程……您知道……容易。

Cheers.

干杯。

→ Other Stories by Greg Perry

→Greg Perry的其他故事