How to add new or update existing localization to this project

[craftersmine]

You want to add a new localization to this project? Great, this topic will tell you all nuances with localizing application.

First of all.

Do you know what a RESX file is? If yes, this is great, you can straight up go to localizing an app to your favourite language! If not, don't worry, I'll explain.

What a RESX file is

RESX file is just a text file that contains XML code, representing a .NET resources. Here is a part of the Locale.resx file:

<?xml version="1.0" encoding="utf-8"?>
<root>
  <xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
    <xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
    <xsd:element name="root" msdata:IsDataSet="true">
      <xsd:complexType>
        <xsd:choice maxOccurs="unbounded">
          <xsd:element name="metadata">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" />
              </xsd:sequence>
              <xsd:attribute name="name" use="required" type="xsd:string" />
              <xsd:attribute name="type" type="xsd:string" />
              <xsd:attribute name="mimetype" type="xsd:string" />
              <xsd:attribute ref="xml:space" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="assembly">
            <xsd:complexType>
              <xsd:attribute name="alias" type="xsd:string" />
              <xsd:attribute name="name" type="xsd:string" />
            </xsd:complexType>
          </xsd:element>
        </xsd:choice>
      </xsd:complexType>
    </xsd:element>
  </xsd:schema>

  <!-- /.../ -->

  <data name="CrashHandlerWindow.Buttons.CopyToClipboard" xml:space="preserve">
    <value>Copy Info to Clipboard</value>
  </data>
  <data name="CrashHandlerWindow.Buttons.OpenIssues" xml:space="preserve">
    <value>Open GitHub Issues</value>
  </data>
  <data name="CrashHandlerWindow.Buuttons.CloseApp" xml:space="preserve">
    <value>Close application</value>
  </data>
  <data name="CrashHandlerWindow.Description" xml:space="preserve">
    <value>In order to debug and fix the problem, please open an issue at project GitHub page. Please include following information in text format.</value>
  </data>
  <data name="CrashHandlerWindow.Label.ExceptionMessage" xml:space="preserve">
    <value>Exception message:</value>
  </data>

  <!-- /.../ -->

  <data name="SettingsWindow.Title" xml:space="preserve">
    <value>Settings</value>
  </data>
</root>

Scary, right? Well, not really, to localize a RESX, you really need to touch only <value><!-- plain text --></value> part.

For example, if I want to localize Settings window title, I'll find part:

<data name="SettingsWindow.Title" xml:space="preserve">
  <value>Settings</value>
</data>

And change the value to, for example Настройки, which means Settings in Russian. Final code will look like that:

<data name="SettingsWindow.Title" xml:space="preserve">
  <value>Настройки</value>
</data>

See, that's not that hard! 👍 However, you need to keep in mind that some specific symbols are reserved to XML language, for example < and > symbols, these are Tag definition symbols, which means if you put them into value tag like that: <value><</value>, it will result in a syntax error! But how to avoid it? That's also easy! You just need to use special escape-sequences, like < and > for < and > symbols, the final XML will look like that <value>&lt;</value>. There are only five reserved characters, so, if you need to input them, use this table:

Special character	escaped form	gets replaced by
Ampersand	&	&
Less-than	&lt;	<
Greater-than	&gt;	>
Quotes	&quot;	"
Apostrophe	&apos;	'

You know what a RESX is

Great! You are ready to localize app!

Fork a repository

Now you need to make a fork of the repository to your account in order to edit files. You can learn how to do this here. This will create a copy of this repository on your account.

Clone repository locally

Do however you want, use a desktop client or use a CLI, that's up to you! If you are pretty new to it, you can use desktop client, because it will be easier. Clone the repo wherever you want, just remember that location.

Make a copy of a locale file

Now you need to locate a craftersmine.LeagueBalancer\Localization\Locale.resx file. MAKE SURE YOU ARE COPYING RESX FILE RATHER THAN CS! These are completely different files, and you don't need a cs file if you only want to localize your app!

After you copied a file, you need to replace it's extension to specific locale. For example, ru-ru for Russia (Russian Federation), you can find all list of the locale codes here. Just find needed locale, and change the _ symbol to -. New file should be named to something like that: Locale.ru-ru.resx

Localize the strings

Now open newly copied file in your beloved text editor. Notepad++ or Visual Studio Code is recommended, or even better use Visual Studio with .NET development environment. These editors have syntax-highlighting, which will make distinguishing tags easier. Make sure that the length of your strings are not long relative to English variant (English variant, or Invariant file is Locale.resx file, a file without any locale extension). MAKE SURE YOU DON'T CHANGE ANY OF DEVELOPER NAMES IN STRINGS! THIS WILL MAKE YOUR PR DECLINED

Validate your XML!

Please, validate your XML, for example, here, or if you are using Visual Studio Code or Visual Studio itself, it will show you error right away! Sometimes you can remove required symbol or forget that some symbols are needed to be escaped. XML validation will show what errors you've made and you'll be able to fix them. The source files are 100% correct. If your file contains errors, the application won't compile, and it will be required for me to fix your mistakes!

Commit your work

Make a new commit with created file to your repository, you should know how to do this, but if you don't here is how to do it in desktop client. Name your commit appropriately, for example Added ru-ru localization, use only English language in commit titles and descriptions, avoid of long commit titles as much as possible.

Make a pull request

In order to add your localization from your repository, you are required to make a Pull Request, you can learn how to do it here. Please, pay attention on merge conflicts, because, if there are conflicts, you are probably doing something wrong. Make sure that you are not changing any other files and your fork of repository is up-to-date with upstream repository, you can see how it's done here. Please, use only English language in titles and descriptions of pull requests

You've made a pull request what's next?

Just wait! Sometimes it takes some work for me to implement a new features into an app, sometimes I just don't have time to do so. You will receive a notification on GitHub if your pull request was merged into upstream repository and will receive a notification in app when update is released.

I've pushed the changes, but I want to fix mistake

Don't worry, you can fix mistake, make a new commit, and it will appear in pull request immediatelly, if you commited to the same branch.

Pull request accepted and closed, but I want to fix mistake

Do the same actions as if you making just a change like above, the only difference with this, is that you need to create a new pull request after commiting new changes.

I've made a pull request, but it was closed without merge

Well, I've declined your pull request due to some issues, for example massive conflicts, issues with files, changed info that shouldn't be changed (ex. developer name in strings, etc.). Read your pull request discussion in order to figure out what went wrong.

What do I need to do if I want to test the locale?

Well, that's an interesting question, first of all, you need to have an experience in coding in C# and WPF and in coding in general. If you don't have such experience, I would step-away from trying it and wait until the localization will be released or you get a PR comment about changing something, for example make a string shorter, because it don't fit inside of the button.
If you have such experience, just open a solution file, wait for it to restore NuGet packages, and then launch in Debug configuration.

There are still questions! What do I do?

Don't worry, you can ask these questions here, or start a new topic, but the wisest developer will say to you just google it.