Add documentation and few fixed as a result of writing the docs

Author: jonnydgreen

.vscode/settings.json

@@ -20,6 +20,7 @@
     "gutignore",
     "lanczos",
     "maskable",
+    "msgctxt",
     "neighbor",
     "npcs",
     "onready",

CONTRIBUTING.md

@@ -13,6 +13,14 @@ Ensure the following are installed:
 
 - [Godot](https://godotengine.org/)
 
+## Conventions
+
+### GDScript
+
+Parley does not enforce a strict style guide but where possible, it is
+recommended to follow the Godot GDScript style guide as described
+[here](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_styleguide.html).
+
 ## Documentation
 
 Documentation is a vital part of Parley and should always be included for any

addons/parley/models/parley_context.gd

@@ -2,6 +2,10 @@ class_name ParleyContext extends Object
 
 
 #region DEFS
+const Settings = preload("../settings.gd")
+const Constants = preload("../constants.gd")
+
+
 ## The current Dialogue Sequence AST of the Parley Context.
 var dialogue_sequence_ast: ParleyDialogueSequenceAst = ParleyDialogueSequenceAst.new(): set = _set_dialogue_sequence_ast
 
@@ -28,9 +32,10 @@ signal dialogue_ended
 
 
 #region LIFECYCLE
-func _init(p_dialogue_sequence_ast: ParleyDialogueSequenceAst = ParleyDialogueSequenceAst.new(), data: Dictionary = {}) -> void:
+func _init(p_dialogue_sequence_ast: ParleyDialogueSequenceAst = ParleyDialogueSequenceAst.new(), data: Dictionary = {}, p_translation_mode: TranslationMode = TranslationMode.Auto) -> void:
 	dialogue_sequence_ast = p_dialogue_sequence_ast
 	p_data = data
+	translation_mode = p_translation_mode
 #endregion
 
 
@@ -46,8 +51,11 @@ func _set_dialogue_sequence_ast(new_dialogue_sequence_ast: ParleyDialogueSequenc
 
 
 #region FACTORY
-static func create(p_dialogue_sequence_ast: ParleyDialogueSequenceAst, data: Dictionary = {}) -> ParleyContext:
-	return ParleyContext.new(p_dialogue_sequence_ast, data)
+@warning_ignore("INT_AS_ENUM_WITHOUT_MATCH") # This is used as a default and handled within the function so this is fine to not match
+static func create(p_dialogue_sequence_ast: ParleyDialogueSequenceAst, data: Dictionary = {}, p_translation_mode: TranslationMode = -1 as TranslationMode) -> ParleyContext:
+	var settings_translation_mode: TranslationMode = TranslationMode[Settings.get_setting(Constants.TRANSLATION_MODE)]
+	var ctx_translation_mode: TranslationMode = p_translation_mode if p_translation_mode != -1 else settings_translation_mode
+	return ParleyContext.new(p_dialogue_sequence_ast, data, ctx_translation_mode)
 #endregion
 
 

addons/parley/parley_export.gd

@@ -143,17 +143,17 @@ static func _export(file_type: ParleyExportModal.FileType, export_type: ParleyEx
 					continue
 				if key_values.size() < 2:
 					continue
-				var value: String = key_values[1]
+				var entry_locale_value: String = key_values[1]
 
 				# Handle existing lines
 				var existing_line_index: int = existing_lines_map.get(entry_key, -1)
 				if existing_line_index >= 0 and existing_line_index < lines_to_store.size():
-					var column_index: int = headers.find(locale)
+					var project_locale_column_index: int = headers.find(locale)
 					var existing_line: PackedStringArray = lines_to_store[existing_line_index]
-					var override_value: bool = false
-					if column_index >= 0:
-						var existing_value: String = existing_line[column_index]
-						override_value = existing_value != value and value != entry_key
+					var should_override_value: bool = false
+					if project_locale_column_index >= 0:
+						var existing_value: String = existing_line[project_locale_column_index]
+						should_override_value = existing_value != entry_locale_value
 
 					var existing_line_to_store: PackedStringArray = PackedStringArray([key_values[0]])
 					var index: int = 1
@@ -164,7 +164,7 @@ static func _export(file_type: ParleyExportModal.FileType, export_type: ParleyEx
 							# TODO: support _notes
 							var _result: int = existing_line_to_store.append(column_value)
 						else:
-							var _result: int = existing_line_to_store.append(value if override_value else column_value)
+							var _result: int = existing_line_to_store.append(entry_locale_value if should_override_value else column_value)
 						index += 1
 					lines_to_store[existing_line_index] = existing_line_to_store
 					continue
@@ -177,7 +177,7 @@ static func _export(file_type: ParleyExportModal.FileType, export_type: ParleyEx
 						# TODO: support _notes
 						var _result: int = new_line_to_store.append("")
 					else:
-						var _result: int = new_line_to_store.append(value)
+						var _result: int = new_line_to_store.append(entry_locale_value)
 				lines_to_store.append(new_line_to_store)
 		_:
 			var message: String = "Unable to export: Unknown file type (file_type:%s, export_type:%s)" % [file_type_name, export_type_name]

addons/parley/parley_import.gd

@@ -16,31 +16,31 @@ static func import_dialogue_text_translation(file_type: ParleyImportModal.FileTy
 		return [ERR_INVALID_DATA if file_result == OK else file_result, message]
 
 	var index: int = 0
-	var key: StringName = ParleyUtils.translation.get_csv_key_name()
+	var key_name: StringName = ParleyUtils.translation.get_csv_key_name()
 	var locale: StringName = ParleyUtils.translation.get_locale()
-	var headers: PackedStringArray = PackedStringArray([key, locale])
+	var headers: PackedStringArray = PackedStringArray([key_name, locale])
 	const key_index: int = 0
-	var translation_index: int = 1
+	var project_locale_column_index: int = headers.find(locale)
 	var lines_map: Dictionary[String, String] = {}
 	while !file.eof_reached():
 		var line: PackedStringArray = file.get_csv_line()
 		if line.size() >= 2 and line[0] != "":
 			if index == 0:
 				headers = line
-				var found_translation_index: int = headers.find(locale)
+				project_locale_column_index = headers.find(locale)
 				# We assume that key index is always 0
-				if found_translation_index > key_index:
+				if project_locale_column_index > key_index:
 					pass
 				else:
 					var message: String = "Unable to import: cannot find valid translation index: (headers:%s, line:%s, locale:%s)" % [headers, line, locale]
 					push_error(ParleyUtils.log.error_msg(message))
 					file.close()
 					return [ERR_INVALID_DATA, message]
-			elif line.size() >= translation_index:
-				var translation_field: String = line[translation_index]
+			elif project_locale_column_index >= 0 and project_locale_column_index < line.size():
+				var translation_field: String = line[project_locale_column_index]
 				lines_map[line[key_index]] = translation_field
 			else:
-				var message: String = "Unable to import: cannot find valid translation field: (headers:%s, line:%s, locale:%s)" % [headers, line, locale]
+				var message: String = "Unable to import: cannot find valid translation field matching the project locale: (headers:%s, line:%s, locale:%s)" % [headers, line, locale]
 				push_error(ParleyUtils.log.error_msg(message))
 				file.close()
 				return [ERR_INVALID_DATA, message]
@@ -49,10 +49,17 @@ static func import_dialogue_text_translation(file_type: ParleyImportModal.FileTy
 
 	var updated: bool = false
 	for node_ast: ParleyNodeAst in dialogue_sequence_ast.nodes:
+		if not [ParleyDialogueSequenceAst.Type.DIALOGUE, ParleyDialogueSequenceAst.Type.DIALOGUE_OPTION].has(node_ast.type):
+			continue
+
 		var field: StringName = &"text"
 		var text_translation_key: String = ParleyUtils.translation.get_msg_ctx(node_ast, field)
-		var updated_text: String = lines_map.get(text_translation_key, "")
-		if text_translation_key and updated_text and is_instance_of(updated_text, TYPE_STRING):
+		var text: String = node_ast.get("text") if node_ast.get("text") else ""
+		var key: String = text_translation_key if text_translation_key else text
+		var updated_text: String = lines_map.get(key, "")
+		if updated_text and is_instance_of(updated_text, TYPE_STRING) and text != updated_text:
+			if not text_translation_key:
+				ParleyUtils.translation.set_msg_ctx(node_ast, field, key) 
 			node_ast.set(field, updated_text)
 			updated = true
 

addons/parley/settings.gd

@@ -15,7 +15,7 @@ static var DEFAULT_SETTINGS: Dictionary = {
 	ParleyConstants.ACTION_STORE_PATH: "res://actions/action_store.tres",
 	ParleyConstants.FACT_STORE_PATH: "res://facts/fact_store.tres",
 	# Internationalisation
-	ParleyConstants.TRANSLATION_MODE: ParleyContext.TranslationMode.keys()[ParleyContext.TranslationMode.PO],
+	ParleyConstants.TRANSLATION_MODE: ParleyContext.TranslationMode.keys()[ParleyContext.TranslationMode.Auto],
 	ParleyConstants.TRANSLATION_CSV_HEADER_KEY: &"keys",
 	# Test Dialogue Sequence
 	# We can't preload this because of circular deps so let's

addons/parley/utils/parley_util.gd

@@ -108,6 +108,14 @@ class translation:
 		return ""
 
 
+	## Set the translation context for a node field.
+	## If it can't be found, do nothing.
+	static func set_msg_ctx(node: ParleyNodeAst, field: String, value: String, suffix: StringName = &"_translation_key") -> void:
+		if not is_instance_of(node.get(field + suffix), TYPE_STRING):
+			return
+		return node.set(field + suffix, value)
+
+
 	## Translate the input string
 	static func translate(input: StringName) -> String:
 		var instance: Object = new()