Created Locales (markdown)

Locales.md

@@ -0,0 +1,77 @@
+# Internationalization (I18N) / Locales API
+I18N is the concept of making your app translatable. In ACF, we automatically load English language tables (and potentially more), and provide the tools to let you change the messaging.
+
+## Autoloading .property files for your plugin
+This method should work as long as you do not need to let your end-users adjust the messaging (if you do, see below for File System based)
+
+For Bukkit, Bungee and Sponge, if you create a file named `acf-YourPlugin_<language>.properties` in your resources folder, ACF will automatically load this file.
+
+for language, use `en` for english, or any of the other Locale based codes (de, fr, es, etc)
+
+You may override any predefined key and or load new languages this way.
+
+However, in order to add a new language, you must first, before ever calling `manager.getLocales()`, call `manager.addSupportedLanguage(Locale.XXXX)`.
+
+You must do this before accessing .getLocales(), as getLocales will load the bundle.
+
+If you need to manually load a bundle that is not a "Supported Language", or just want to use alternate file names, you may call:
+```java
+// To load for all supported language locales
+manager.getLocales().addMessageBundle("bundleName");
+// to load for an explicit locale (may or may not be supported)
+manager.getLocales().addMessageBundle("bundleName", locale);
+```
+
+## Using File System based language files
+`CommandManager.getLocales` provides an API to load messages into the language table. 
+
+For the Bukkit platform, YAML based API (and an API for anything that supports the FileConfiguration API) has been provided.
+If you create a YAML file such as `lang_en.yaml`, in the following format:
+
+```yaml
+acf-minecraft:
+  multiple_players_match: "<language here">
+  # ... more
+acf-core:
+  permission_denied: "Perm denied message here"
+  # ... more
+```
+Then you may load it with 
+```java
+manager.getLocales().loadYamlLanguageFile("lang_en.yml", Locale.ENGLISH);
+```
+
+Repeat this for other languages.
+
+
+## Changing Message Colors
+While not directly part of the Locales API, it strongly relates. Messages in ACF route through a platform agnostic Message Format system.
+
+ACF is designed to support multiple colors, but not (currently) other formatting options.
+
+Everything is color 1 by default, unless overridden with `<c#>TEXT</c#>` tags, for example:
+`Error: Multiple players matched <c2>{search}</c2> <c3>({all})</c3>, please be more specific.`
+
+This will use color 2 for {Search}, color 3 for the list of all valid options, and color 1 for everything else.
+
+Colors are registered on a per message type basis, so you may change them like so:
+
+```java
+// Sets 1,2,3 (and more, as many colors you provide)
+manager.setFormat(MessageType.ERROR, ChatColor.ORANGE, ChatColor.RED, ChatColor.YELLOW);
+// Change only a specific color
+manager.setFormat(MessageType.ERROR, 3, ChatColor.ORANGE);
+```
+
+If you wish to use other formatting options (such as italic/bold for Minecraft), you may use those characters in your language files, as long as you are not sharing those language files between another platform (such as Sponge) which might not understand it.
+
+But as Minecraft stands, I believe all 3 platforms support the section symbol codes.
+
+## Default Locale
+ACF defaults to English as the default Locale as that is what we provide language files for. 
+Currently, only the default locale is used to look up messages, as we have not completed the work yet to do per-player contextual Locales.
+
+So if you need to use non English language for ACF, then simply ensure you load messages completely for your language, and then call:
+```java
+manager.getLocales().setDefaultLocale(locale);
+```