@quenty/clienttranslator 4.4.0 → 4.5.0-canary.241.a4e8214.0

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [4.5.0-canary.241.a4e8214.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/clienttranslator@4.4.1...@quenty/clienttranslator@4.5.0-canary.241.a4e8214.0) (2022-01-03)
+
+
+### Features
+
+* Add JSONTranslator:ObserveFormatByKey(key, argData) ([60c9ece](https://github.com/Quenty/NevermoreEngine/commit/60c9ecec2679f4392f1ee8c4f3008dfe9ec68ffa))
+* Suppress localization warnings when game is not published ([f0961eb](https://github.com/Quenty/NevermoreEngine/commit/f0961ebbc2359a8e7f89576664c0fb80ca9bfdae))
+
+
+
+
+
+## [4.4.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/clienttranslator@4.4.0...@quenty/clienttranslator@4.4.1) (2021-12-30)
+
+**Note:** Version bump only for package @quenty/clienttranslator
+
+
+
+
+
 # [4.4.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/clienttranslator@4.3.0...@quenty/clienttranslator@4.4.0) (2021-12-18)
 
 

package/README.md

@@ -1,10 +1,10 @@
 ## ClientTranslator
 <div align="center">
-  <a href="http://quenty.github.io/api/">
-    <img src="https://img.shields.io/badge/docs-website-green.svg" alt="Documentation" />
+  <a href="http://quenty.github.io/NevermoreEngine/">
+    <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/docs.yml/badge.svg" alt="Documentation status" />
   </a>
   <a href="https://discord.gg/mhtGUS8">
-    <img src="https://img.shields.io/badge/discord-nevermore-blue.svg" alt="Discord" />
+    <img src="https://img.shields.io/discord/385151591524597761?color=5865F2&label=discord&logo=discord&logoColor=white" alt="Discord" />
   </a>
   <a href="https://github.com/Quenty/NevermoreEngine/actions">
     <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/build.yml/badge.svg" alt="Build and release status" />
@@ -13,6 +13,8 @@
 
 Gets local translator for player
 
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/JSONTranslator">View docs →</a></div>
+
 ## Installation
 ```
 npm install @quenty/clienttranslator --save

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/clienttranslator",
-  "version": "4.4.0",
+  "version": "4.5.0-canary.241.a4e8214.0",
   "description": "Gets local translator for player",
   "keywords": [
     "Roblox",
@@ -25,12 +25,15 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/loader": "^3.1.1",
-    "@quenty/promise": "^3.3.0",
-    "@quenty/pseudolocalize": "^2.0.0"
+    "@quenty/blend": "2.1.0-canary.241.a4e8214.0",
+    "@quenty/loader": "3.2.0-canary.241.a4e8214.0",
+    "@quenty/maid": "2.0.2",
+    "@quenty/promise": "3.4.0-canary.241.a4e8214.0",
+    "@quenty/pseudolocalize": "2.0.1",
+    "@quenty/rx": "3.6.0-canary.241.a4e8214.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "6eb398e9fb81191f0815885f807ab0cb3bb9bad1"
+  "gitHead": "a4e821471f35998d63f38a4f4a578e07b4e79035"
 }

package/src/Client/JSONTranslator.lua

@@ -1,6 +1,7 @@
----
--- @classmod JSONTranslator
--- @author Quenty
+--[=[
+	Utility function that loads a translator from a folder or a table.
+	@class JSONTranslator
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -12,11 +13,36 @@ local JsonToLocalizationTable = require("JsonToLocalizationTable")
 local PseudoLocalize = require("PseudoLocalize")
 local LocalizationServiceUtils = require("LocalizationServiceUtils")
 local Promise = require("Promise")
+local Observable = require("Observable")
+local Maid = require("Maid")
+local Blend = require("Blend")
+local Rx = require("Rx")
 
 local JSONTranslator = {}
 JSONTranslator.ClassName = "JSONTranslator"
 JSONTranslator.__index = JSONTranslator
 
+--[=[
+	Constructs a new JSONTranslator from the given args.
+
+	```lua
+	local translator = JSONTranslator.new("en", {
+		actions = {
+			respawn = "Respawn {playerName}";
+		};
+	})
+
+	print(translator:FormatByKey("actions.respawn"), { playerName = "Quenty"}) --> Respawn Quenty
+	```
+
+	```lua
+	local translator = JSONTranslator.new(script)
+	-- assume there is an `en.json` underneath the script with valid JSON.
+	```
+
+	@param ... any
+	@return JSONTranslator
+]=]
 function JSONTranslator.new(...)
 	local self = setmetatable({}, JSONTranslator)
 
@@ -39,11 +65,21 @@ function JSONTranslator.new(...)
 	return self
 end
 
+--[=[
+	Returns a promise that will resolve once the translator is loaded from the cloud.
+	@return Promise
+]=]
 function JSONTranslator:PromiseLoaded()
 	return self._promiseTranslator
 end
 
---- Mostly just used for testing,
+--[=[
+	Makes the translator fall back to another translator if an entry cannot be found.
+
+	Mostly just used for testing.
+
+	@param translator JSONTranslator | Translator
+]=]
 function JSONTranslator:FallbackTo(translator)
 	assert(translator, "Bad translator")
 	assert(translator.FormatByKey, "Bad translator")
@@ -51,6 +87,12 @@ function JSONTranslator:FallbackTo(translator)
 	table.insert(self._fallbacks, translator)
 end
 
+--[=[
+	Formats the resulting entry by args.
+	@param key string
+	@param args table?
+	@return Promise<string>
+]=]
 function JSONTranslator:PromiseFormatByKey(key, args)
 	assert(self ~= JSONTranslator, "Construct a new version of this class to use it")
 	assert(type(key) == "string", "Key must be a string")
@@ -60,7 +102,51 @@ function JSONTranslator:PromiseFormatByKey(key, args)
 	end)
 end
 
---- Blocking format until the cloud translations are loaded.
+--[=[
+	Observes the translated value
+	@param key string
+	@param argData table? -- May have observables (or convertable to observables) in it.
+	@return Observable<string>
+]=]
+function JSONTranslator:ObserveFormatByKey(key, argData)
+	assert(self ~= JSONTranslator, "Construct a new version of this class to use it")
+	assert(type(key) == "string", "Key must be a string")
+
+	local argObservable
+	if argData then
+		local args = {}
+		for argKey, value in pairs(argData) do
+			args[argKey] = Blend.toPropertyObservable(value) or Rx.of(value)
+		end
+
+		argObservable = Rx.combineLatest(args)
+	else
+		argObservable = nil
+	end
+
+	return Observable.new(function(sub)
+		local maid = Maid.new()
+
+		maid:GivePromise(self._promiseTranslator:Then(function()
+			if argObservable then
+				maid:GiveTask(argObservable:Subscribe(function(args)
+					sub:Fire(self:FormatByKey(key, args))
+				end))
+			else
+				sub:Fire(self:FormatByKey(key, nil))
+			end
+		end))
+
+		return maid
+	end)
+end
+
+--[=[
+	Formats or errors if the cloud translations are not loaded.
+	@param key string
+	@param args table?
+	@return string
+]=]
 function JSONTranslator:FormatByKey(key, args)
 	assert(self ~= JSONTranslator, "Construct a new version of this class to use it")
 	assert(type(key) == "string", "Key must be a string")
@@ -140,6 +226,9 @@ function JSONTranslator:_formatByKeyTestMode(key, args)
 	return key
 end
 
+--[=[
+	Cleans up the translator and deletes the localization table if it exists.
+]=]
 function JSONTranslator:Destroy()
 	self._localizationTable:Destroy()
 	self._localizationTable = nil

package/src/Client/LocalizationServiceUtils.lua

@@ -1,6 +1,6 @@
----
--- @module LocalizationServiceUtils
--- @author Quenty
+--[=[
+	@class LocalizationServiceUtils
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -8,6 +8,7 @@ local LocalizationService = game:GetService("LocalizationService")
 local RunService = game:GetService("RunService")
 
 local Promise = require("Promise")
+local ERROR_PUBLISH_REQUIRED = "Publishing the game is required to use GetTranslatorForPlayerAsync API."
 
 local LocalizationServiceUtils = {}
 
@@ -49,7 +50,9 @@ function LocalizationServiceUtils.promiseTranslator(player)
 	end)
 
 	return asyncTranslatorPromise:Catch(function(err)
-		warn(("[LocalizationServiceUtils.promiseTranslator] - %s"):format(tostring(err)))
+		if err ~= ERROR_PUBLISH_REQUIRED then
+			warn(("[LocalizationServiceUtils.promiseTranslator] - %s"):format(tostring(err)))
+		end
 
 		-- Fallback to just local stuff
 		local translator = LocalizationService:GetTranslatorForPlayer(player)

package/src/Shared/JsonToLocalizationTable.lua

@@ -1,15 +1,20 @@
---- Utility to build a localization table from json, intended to be used with rojo. Can also handle Rojo json
--- objects turned into tables!
--- @module JsonToLocalizationTable
+--[=[
+	Utility to build a localization table from json, intended to be used with rojo. Can also handle Rojo json
+	objects turned into tables!
+
+	@class JsonToLocalizationTable
+]=]
 
 local HttpService = game:GetService("HttpService")
 
 local JsonToLocalizationTable = {}
 
---- Recursively iterates through the object to construct strings and add it to the localization table
--- @param localeId The localizationid to add
--- @param baseKey the key to add
--- @param object The value to iterate over
+--[[
+	Recursively iterates through the object to construct strings and add it to the localization table
+	@param localeId string -- The localizationid to add
+	@param baseKey string -- the key to add
+	@param object any -- The value to iterate over
+]]
 local function recurseAdd(localizationTable, localeId, baseKey, object)
 	if baseKey ~= "" then
 		baseKey = baseKey .. "."
@@ -34,9 +39,11 @@ local function recurseAdd(localizationTable, localeId, baseKey, object)
 	end
 end
 
---- Extracts the locale from the name
--- @param name The name to parse
--- @return The locale
+--[=[
+	Extracts the locale from the name
+	@param name string -- The name to parse
+	@return string -- The locale
+]=]
 function JsonToLocalizationTable.localeFromName(name)
 	if name:sub(-5) == ".json" then
 		return name:sub(1, #name-5)
@@ -45,8 +52,10 @@ function JsonToLocalizationTable.localeFromName(name)
 	end
 end
 
---- Loads a folder into a localization table
--- @parm folder A Roblox folder with StringValues containing JSON, named with the localization in mind
+--[=[
+	Loads a folder into a localization table
+	@param folder Folder -- A Roblox folder with StringValues containing JSON, named with the localization in mind
+]=]
 function JsonToLocalizationTable.loadFolder(folder)
 	local localizationTable = Instance.new("LocalizationTable")
 	for _, item in pairs(folder:GetDescendants()) do
@@ -61,6 +70,12 @@ function JsonToLocalizationTable.loadFolder(folder)
 	return localizationTable
 end
 
+--[=[
+	Extracts the locale from the folder, or a locale and table.
+	@param first Instance | string
+	@param second table?
+	@return LocalizationTable
+]=]
 function JsonToLocalizationTable.toLocalizationTable(first, second)
 	if typeof(first) == "Instance" then
 		local result = JsonToLocalizationTable.loadFolder(first)
@@ -75,16 +90,24 @@ function JsonToLocalizationTable.toLocalizationTable(first, second)
 	end
 end
 
+--[=[
+	Extracts the locale from the name
+	@param localeId string -- the defaultlocaleId
+	@param dataTable table -- Data table to load from
+	@return LocalizationTable
+]=]
 function JsonToLocalizationTable.loadTable(localeId, dataTable)
 	local localizationTable = Instance.new("LocalizationTable")
 	recurseAdd(localizationTable, localeId, "", dataTable)
 	return localizationTable
 end
 
---- Adds json to a localization table
--- @param localizationTable The localization table to add to
--- @param localeId The localeId to use
--- @param json The json to add with
+--[=[
+	Adds json to a localization table
+	@param localizationTable LocalizationTable -- The localization table to add to
+	@param localeId string -- The localeId to use
+	@param json string -- The json to add with
+]=]
 function JsonToLocalizationTable.addJsonToTable(localizationTable, localeId, json)
 	local decodedTable = HttpService:JSONDecode(json)
 	recurseAdd(localizationTable, localeId, "", decodedTable)