First iteration of translation

rust/src/fluent/generator.rs

@@ -11,6 +11,10 @@ use godot::global::Error as GdErr;
 
 use super::{project_settings::{INVALID_MESSAGE_HANDLING_SKIP, PROJECT_SETTING_GENERATOR_INVALID_MESSAGE_HANDLING, PROJECT_SETTING_GENERATOR_LOCALES, PROJECT_SETTING_GENERATOR_PATTERNS}, FluentPackedSceneTranslationParser, FluentTranslationParser};
 
+/// Allows generating Fluent Translation List (FTL) files by extracting keys.
+/// 
+/// For now, this class only supports [PackedScene] files and is completely loaded via Project Settings configuration.
+/// It may be updated in the future to receive a proper API and editor integration.
 #[derive(GodotClass)]
 #[class(no_init)]
 pub struct FluentGenerator {
@@ -27,6 +31,7 @@ pub type MessageGeneration = HashMap<String, String>;
 #[godot_api]
 impl FluentGenerator {
     #[func]
+    /// Create a new [FluentGenerator] instance using the Project Settings for configuration.
     pub fn create() -> Gd<Self> {
         let project_settings = ProjectSettings::singleton();
         let locales = PackedStringArray::from_variant(&project_settings.get_setting(PROJECT_SETTING_GENERATOR_LOCALES.into()));
@@ -47,6 +52,9 @@ impl FluentGenerator {
     }
 
     #[func]
+    /// Generate Fluent Translation List (FTL) files, creating or updating files as necessary.
+    /// If a message is already translated, it will not be updated.
+    /// Deleted keys are currently left untouched and must be manually purged.
     pub fn generate(&self) {
         // Collect source files and batched write operations.
         let files = self.get_matching_files();

rust/src/fluent/global.rs

@@ -3,6 +3,7 @@ use godot::classes::ResourceLoader;
 
 use super::ResourceFormatLoaderFluent;
 
+/// Singleton for handling Fluent Translation. For internal use only.
 #[derive(GodotClass)]
 #[class(base=Object, init)]
 pub struct FluentI18nSingleton {

rust/src/fluent/importer.rs

@@ -6,6 +6,9 @@ use godot::global::Error as GdErr;
 
 use super::{locale::{compute_locale, compute_message_pattern}, project_settings::*, TranslationFluent};
 
+/// Loads Fluent Translation List (FTL) files.
+/// 
+/// This loader is already registered and does usually not need to be manually used. Use [method @GDScript.load] on a `.ftl` file instead.
 #[derive(GodotClass)]
 #[class(base=ResourceFormatLoader)]
 pub struct ResourceFormatLoaderFluent {

rust/src/fluent/translation.rs

@@ -13,9 +13,21 @@ use crate::utils::get_single_regex_match;
 
 use super::project_settings::{PROJECT_SETTING_FALLBACK_LOCALE, PROJECT_SETTING_PARSE_ARGS_IN_MESSAGE, PROJECT_SETTING_UNICODE_ISOLATION};
 
+/// Translation resource containing one or more Fluent Translation Lists (FTLs).
+/// 
+/// Can be loaded from a `.ftl` file via [method @GDScript.load] or manually populated using [method add_bundle_from_text].
+/// When using the forked build of the add-on, you can also add a `.ftl` file to the Project Settings in the Localization -> Translations tab.
+/// 
+/// Any time a [TranslationFluent] instance is created by the add-on, the [member message_pattern] and [member locale] are automatically filled
+/// depending on the corresponding Project Settings.
 #[derive(GodotClass)]
 #[class(base=Translation)]
 pub struct TranslationFluent {
+    /// Automatically wrap every message with the specified regex pattern, defined as a string pattern.
+    /// This can be specified in order to create custom namespaces for your translations.
+    /// 
+    /// For example, if a message `hello = abc` is defined with the pattern `^test_(.+)$`, then you must call `tr("test_hello")` to get the message's translation.
+    /// **Note**: The regex pattern is case sensitive by default. Prefix your pattern with `(?i)` in order to make it case insensitive.
     #[var(get = get_message_pattern, set = set_message_pattern)]
     message_pattern: GString,
     message_pattern_regex: Option<Gd<RegEx>>,
@@ -203,6 +215,10 @@ impl TranslationFluent {
         Some(text.into_owned())
     }
 
+    /// Attach arguments (also known as variables) to a message.
+    /// A translation can use these values using `{ $variableName }` syntax in the FTL.
+    /// 
+    /// This method is only needed when using the default version of the add-on, as the forked build includes an additional `args` parameter to the different translation methods.
     #[func]
     pub fn args(msg: StringName, args: Dictionary) -> StringName {
         let args = var_to_str(Variant::from(args)).to_string();
@@ -236,6 +252,13 @@ impl TranslationFluent {
         (msg, Default::default())
     }
 
+    /// Add a Fluent Translation List (FTL) text to this translation.
+    /// This method is automatically called when the add-on creates a [TranslationFluent] resource for you (e.g. when using [method @GDScript.load]).
+    /// 
+    /// Returns an [enum Error] value whether the data was successfully added.
+    /// 
+    /// **Note**: When this method is called, certain Project Settings values are read.
+    /// Changing these Project Settings after this call will not update already existing [TranslationFluent] resources.
     #[func]
     pub fn add_bundle_from_text(&mut self, text: String) -> GdErr {
         let res = FluentResource::try_new(text);