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 {
@@ -26,6 +30,7 @@ pub type MessageGeneration = HashMap<String, String>;
 
 #[godot_api]
 impl FluentGenerator {
+ /// Create a new [FluentGenerator] instance using the Project Settings for configuration.
  #[func]
  pub fn create() -> Gd<Self> {
  let project_settings = ProjectSettings::singleton();
@@ -46,6 +51,9 @@ impl FluentGenerator {
  })
  }
 
+ /// 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.
  #[func]
  pub fn generate(&self) {
  // Collect source files and batched write operations.

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);