Skip to content

Latest commit

 

History

History
215 lines (132 loc) · 8.17 KB

i18n.md

File metadata and controls

215 lines (132 loc) · 8.17 KB

Internationalization

Why Reinvent the Wheel with Another Localization Engine?

ASP.net has an extremely unintuitive and contributor-unfriendly way of localizing applications. Creating and translating resx files is a highly inefficient task because this requires translators having basic knowledge of XML, which is a huge roadblock for open source projects like of ours. Also, if you want to export and import translation files to and from other formats such as xls, csv, sql, it won't be very easy thing to do. Similarly, directly reading and editing the translation file could introduce some side-effects such as AppDomain restart. Enough for now, we will skip about how unfriendly resx files are and focus on what alternative Frapid has to offer.

To overcome these limitations, Frapid uses its own localization engine. When we developed the localization engine, we had these requirements from our past experience:

  • No resx files.
  • Make something which will work on any text editor.
  • The translation process must be very easy and friendly to contributors who want to translate Frapid and MixERP.
  • The translation process must not involve touching multiple files or unnecessary additional steps.
  • Adding new translation files should be plug and play, involving in no AppDomain restart or recycle.
  • Adding a new translation file must automatically reflect changes.
  • The localization engine must support creating strongly-typed resource classes.
  • The localization engine must not only be easy for server side use, but also the same for HTML and JavaScript.

Background

Internationalization in Frapid involves in creating language files (resources) which are saved into the following location:

  • ~/Areas/{YouAppName}/i18n/resources.yaml (Neutral Resource, English (United States))
  • ~/Areas/{YourAppName}/i18n/{CultureCode}/resources.yaml (Translation file)

A language files consists of key/value pairs, as shown in the following code block:

CashFlowStatement: "Cash Flow Statement"
ProfitandLossStatement: "Profit and Loss Statement"
BankAccounts: "Bank Accounts"
CashFlowSetups: "Cash Flow Setups"
....

Please note that the resources are initially loaded dynamically during runtime.

How to Create Strongly-Typed Resources to Use on Server Side?

Copy the batch file recreate-i18n.bat from one of the existing Frapid app and paste it inside yours. We will use Frapid.WebsiteBuilder as an example here. Edit the file, the contents of the batch file would look like this:

@echo off
"..\..\..\bin\frapid.exe" "create resource on Frapid.WebsiteBuilder"

Rename the name of the app here (Frapid.WebsiteBuilder) to match your app name. Save the file. Once you run the batch file, a file I18N.cs will be placed in your application directory. For the first time, you need to include the generated file in Visual Studio.

How to Use Localization on Server Side?

Since statically-typed resources are supported in Frapid framework, you will need to import the namespace first:

using YourAppName;//The full namespace of the strongly typed resource file is YourAppName.I18N

You can now use the translation keys like this:

private string GetMessage()
{
	return I18N.CashFlowStatement;  
}

If the translation is available for the currently-chosen culture, the key will be automatically translated. If no translation is available for the given key, neutral resource (American English) will be returned.

How to Use Localization on Razor Views?

Since Razor Views can contain both csharp and html code blocks, you should consider the csharp code block as server side code. Skip to the next heading if you want to use localization on the client side.

How to Use Localization on Client Side (HTML5/JavaScript)?

The resources are also provided as a dynamic JavaScript file (resources.js) for client-side use. The JavaScript resources are created (and cached in browser) every time the browser sends an HTTP get request to access that file. Along with this, Frapid provides a client side utility called localizable.js, which automatically translates the resources for you. For more information on localizable.js utility, read the documentation here.

How Can I Translate Frapid to a New Language?

It's really simple. Add your desired language in the key Cultures in the configuration file /Resources/Configs/Parameters.config.

Before

<add key="Cultures" value="ar,de,en,es,fr,ne,ru" />

After

<add key="Cultures" value="ar,de,en,es,fr,ne,ru,it" />

Now, enter the following command in Frapid Console:

pack resource

The above command will investigate resources within Frapid and all available modules and pack them into a combined file for each supported culture. If there are translations partially or fully done, Frapid will still keep all translation work intact. The translation package is kept under this directory:

/Packages/i18n

In the example above, we added a new culture called it. This means that all you need is:

Packages/i18n/it.yaml

Send this file to the person or organization providing translation service. Once you get the full translation job done, replace the same file. Now, enter this command in Frapid Console:

unpack resource from it.yaml

This command will automatically take care of putting back the translated work into individual translation files.

I am only interested to translate the app that I created. How can I do that?

At the beginning of this article, you learned about the directory structure of localization files. If you only want to translate your app, make a copy of resources.yaml file and paste it into respective culture folders.

Before

-YourApp
  -i18n
     - recreate-i18n.bat
     - recreate-i18n-paused.bat
     - resources.yaml

After

-YourApp
  -i18n
     - recreate-i18n.bat
     - recreate-i18n-paused.bat
     - resources.yaml
     - ar
       - resources.yaml
     - de
       - resources.yaml
     - es
       - resources.yaml
     - fr
       - resources.yaml
     - ne
       - resources.yaml
     - ru
       - resources.yaml

When publishing your app, ship your application with everything inside i18n directory, except for the batch files, and you're good to go!

How to load resources.js?

Include the resources.js file on your View.

<script src="/i18n/[email protected]().Name"></script>

The static class CultureManager can be located on the namespace Frapid.i18n.

What is Neutral Resource Language of Frapid?

Frapid uses American English spelling, punctuation, and grammar rules for neutral resource language. This does not prevent you from adding new languages.

The neutral resource language is used as fallback if the chosen user interface language does not contain the translation for any particular term. This means that you will see English along with your language during development (and translation) most of the time.

Titles

Titles are headings that are displayed in Frapid. The headings must be very short and concise phrases. The titles must follow "Rules of Title Capitalization".

Rules of Title Capitalization

Remember:

  1. Prepositions, conjunctions, and articles should not be capitalized.
  2. The first word of the title must be capitalized.

Incorrect

  • The old man and the sea
  • The Old Man And The Sea

Correct

The Old Man and the Sea

NB

Everything except titles follows normal capitalization rule.

Sentences

Sentences must end with a period (or full stop).

Questions

Questions are displayed to users in order for them to proceed with what to do next. Since questions can be informative, descriptive, and suggestive, they can contain multiple sentences. In those cases, the closing sentence must be a question.

Errors

Errors are displayed to users when something bad happens. Whenever you are throwing errors, use this class to create resources. It is okay for an error to end with an exclamation (!) mark or a period (.).

Back to Developer Documentation