@quenty/clienttranslator 6.3.1 → 7.0.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [7.0.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/clienttranslator@6.3.1...@quenty/clienttranslator@7.0.0) (2022-08-14)
+
+
+### Features
+
+* Add NumberLocalizationUtils based upon Roblox's localization code. ([89e75db](https://github.com/Quenty/NevermoreEngine/commit/89e75db2d1c69c2030568290195a5a9bbba5517a))
+
+
+
+
+
 ## [6.3.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/clienttranslator@6.3.0...@quenty/clienttranslator@6.3.1) (2022-08-11)
 
 **Note:** Version bump only for package @quenty/clienttranslator

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/clienttranslator",
-  "version": "6.3.1",
+  "version": "7.0.0",
   "description": "Gets local translator for player",
   "keywords": [
     "Roblox",
@@ -25,16 +25,16 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/blend": "^4.3.1",
-    "@quenty/instanceutils": "^5.2.0",
+    "@quenty/blend": "^5.0.0",
+    "@quenty/instanceutils": "^6.0.0",
     "@quenty/loader": "^5.0.0",
     "@quenty/maid": "^2.4.0",
     "@quenty/promise": "^5.1.0",
-    "@quenty/pseudolocalize": "^2.1.0",
-    "@quenty/rx": "^5.2.0"
+    "@quenty/pseudolocalize": "^3.0.0",
+    "@quenty/rx": "^6.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "45ffe88b893e29690163a42c3830c983f6098a59"
+  "gitHead": "dbb62609f980983cc32da90acfef13e30ed41113"
 }

package/src/Client/JSONTranslator.lua

@@ -20,13 +20,14 @@ local RxInstanceUtils = require("RxInstanceUtils")
 
 local JSONTranslator = {}
 JSONTranslator.ClassName = "JSONTranslator"
+JSONTranslator.ServiceName = "JSONTranslator"
 JSONTranslator.__index = JSONTranslator
 
 --[=[
 	Constructs a new JSONTranslator from the given args.
 
 	```lua
-	local translator = JSONTranslator.new("en", {
+	local translator = JSONTranslator.new("MyTranslator", en", {
 		actions = {
 			respawn = "Respawn {playerName}";
 		};
@@ -40,14 +41,18 @@ JSONTranslator.__index = JSONTranslator
 	-- assume there is an `en.json` underneath the script with valid JSON.
 	```
 
+	@param translatorName string -- Name of the translator. Used for source.
 	@param ... any
 	@return JSONTranslator
 ]=]
-function JSONTranslator.new(...)
+function JSONTranslator.new(translatorName, ...)
 	local self = setmetatable({}, JSONTranslator)
 
+	assert(type(translatorName) == "string", "Bad translatorName")
+	self.ServiceName = translatorName
+
 	-- Cache localizaiton table, because it can take 10-20ms to load.
-	self._localizationTable = JsonToLocalizationTable.toLocalizationTable(...)
+	self._localizationTable = JsonToLocalizationTable.toLocalizationTable(translatorName, ...)
 	self._englishTranslator = self._localizationTable:GetTranslator("en")
 	self._fallbacks = {}
 

package/src/Client/NumberLocalizationUtils.lua

@@ -0,0 +1,317 @@
+--[=[
+	NumberLocalizationUtils script from Roblox's player scripts in handling the leaderboard.
+
+	Example locale-sensitive number formatting:
+	https://docs.oracle.com/cd/E19455-01/806-0169/overview-9/index.html
+
+	Locale specification:
+	[DECIMAL_SEPARATOR] = string for decimal point, if needed
+	[GROUP_DELIMITER] = string for groupings of numbers left of the decimal
+	List section = abbreviations for language, in increasing order
+
+	Missing features in this code:
+	- No support for differences in number of digits per GROUP_DELIMITER.
+	Some Chinese dialects group by 10000 instead of 1000.
+	- No support for variable differences in number of digits per GROUP_DELIMITER.
+	Indian natural language groups the first 3 to left of decimal, then every 2 after that.
+
+	See https://en.wikipedia.org/wiki/Decimal_separator#Digit_grouping
+
+
+	@class NumberLocalizationUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local RoundingBehaviourTypes = require("RoundingBehaviourTypes")
+
+local NumberLocalizationUtils = {}
+
+local DEFAULT_LOCALE = "en-us"
+
+-- Separator aliases to help avoid spelling errors
+local DECIMAL_SEPARATOR = "decimalSeparator"
+local GROUP_DELIMITER = "groupDelimiter"
+
+local localeInfos = {}
+
+localeInfos["en-us"] = {
+	[DECIMAL_SEPARATOR] = ".",
+	[GROUP_DELIMITER] = ",",
+	{ 1, "", },
+	{ 1e3, "K", },
+	{ 1e6, "M", },
+	{ 1e9, "B", },
+}
+
+localeInfos["es-es"] = {
+	[DECIMAL_SEPARATOR] = ",",
+	[GROUP_DELIMITER] = ".",
+	{ 1, "", },
+	{ 1e3, " mil", },
+	{ 1e6, " M", },
+}
+
+localeInfos["fr-fr"] = {
+	[DECIMAL_SEPARATOR] = ",",
+	[GROUP_DELIMITER] = " ",
+	{ 1, "", },
+	{ 1e3, " k", },
+	{ 1e6, " M", },
+	{ 1e9, " Md", },
+}
+
+localeInfos["de-de"] = {
+	[DECIMAL_SEPARATOR] = ",",
+	[GROUP_DELIMITER] = " ",
+	{ 1, "", },
+	{ 1e3, " Tsd.", },
+	{ 1e6, " Mio.", },
+	{ 1e9, " Mrd.", },
+}
+
+localeInfos["pt-br"] = {
+	[DECIMAL_SEPARATOR] = ",",
+	[GROUP_DELIMITER] = ".",
+	{ 1, "", },
+	{ 1e3, " mil", },
+	{ 1e6, " mi", },
+	{ 1e9, " bi", },
+}
+
+localeInfos["zh-cn"] = {
+	[DECIMAL_SEPARATOR] = ".",
+	[GROUP_DELIMITER] = ",", -- Chinese commonly uses 3 digit groupings, despite 10000s rule
+	{ 1, "", },
+	{ 1e3, "千", },
+	{ 1e4, "万", },
+	{ 1e8, "亿", },
+}
+
+localeInfos["zh-cjv"] = {
+	[DECIMAL_SEPARATOR] = ".",
+	[GROUP_DELIMITER] = ",",
+	{ 1, "", },
+	{ 1e3, "千", },
+	{ 1e4, "万", },
+	{ 1e8, "亿", },
+}
+
+localeInfos["zh-tw"] = {
+	[DECIMAL_SEPARATOR] = ".",
+	[GROUP_DELIMITER] = ",",
+	{ 1, "", },
+	{ 1e3, "千", },
+	{ 1e4, "萬", },
+	{ 1e8, "億", },
+}
+
+localeInfos["ko-kr"] = {
+	[DECIMAL_SEPARATOR] = ".",
+	[GROUP_DELIMITER] = ",",
+	{ 1, "", },
+	{ 1e3, "천", },
+	{ 1e4, "만", },
+	{ 1e8, "억", },
+}
+
+localeInfos["ja-jp"] = {
+	[DECIMAL_SEPARATOR] = ".",
+	[GROUP_DELIMITER] = ",",
+	{ 1, "", },
+	{ 1e3, "千", },
+	{ 1e4, "万", },
+	{ 1e8, "億", },
+}
+
+localeInfos["it-it"] = {
+	[DECIMAL_SEPARATOR] = ",",
+	[GROUP_DELIMITER] = " ",
+	{ 1, "", },
+	{ 1e3, " mila", },
+	{ 1e6, " Mln", },
+	{ 1e9, " Mld", },
+}
+
+localeInfos["ru-ru"] = {
+	[DECIMAL_SEPARATOR] = ",",
+	[GROUP_DELIMITER] = ".",
+	{ 1, "", },
+	{ 1e3, " тыс", },
+	{ 1e6, " млн", },
+	{ 1e9, " млрд", },
+}
+
+localeInfos["id-id"] = {
+	[DECIMAL_SEPARATOR] = ",",
+	[GROUP_DELIMITER] = ".",
+	{ 1, "", },
+	{ 1e3, " rb", },
+	{ 1e6, " jt", },
+	{ 1e9, " M", },
+}
+
+localeInfos["vi-vn"] = {
+	[DECIMAL_SEPARATOR] = ".",
+	[GROUP_DELIMITER] = " ",
+	{ 1, "", },
+	{ 1e3, " N", },
+	{ 1e6, " Tr", },
+	{ 1e9, " T", },
+}
+
+localeInfos["th-th"] = {
+	[DECIMAL_SEPARATOR] = ".",
+	[GROUP_DELIMITER] = ",",
+	{ 1, "", },
+	{ 1e3, " พ", },
+	{ 1e4, " ม", },
+	{ 1e5, " ส", },
+	{ 1e6, " ล", },
+}
+
+localeInfos["tr-tr"] = {
+	[DECIMAL_SEPARATOR] = ",",
+	[GROUP_DELIMITER] = ".",
+	{ 1, "", },
+	{ 1e3, " B", },
+	{ 1e6, " Mn", },
+	{ 1e9, " Mr", },
+}
+
+-- Aliases for languages that use the same mappings.
+localeInfos["en-gb"] = localeInfos["en-us"]
+localeInfos["es-mx"] = localeInfos["es-es"]
+
+local function findDecimalPointIndex(numberStr)
+	return string.find(numberStr, "%.") or #numberStr + 1
+end
+
+-- Find the base 10 offset needed to make 0.1 <= abs(number) < 1
+local function findDecimalOffset(number)
+	if number == 0 then
+		return 0
+	end
+
+	local offsetToOnesRange = math.floor(math.log10(math.abs(number)))
+	return -(offsetToOnesRange + 1) -- Offset one more (or less) digit
+end
+
+local function roundToSignificantDigits(number, significantDigits, roundingBehaviourType)
+	local offset = findDecimalOffset(number)
+	local multiplier = 10^(significantDigits + offset)
+	local significand
+	if roundingBehaviourType == RoundingBehaviourTypes.Truncate then
+		significand = math.modf(number * multiplier)
+	else
+		significand = math.floor(number * multiplier + 0.5)
+	end
+	return significand / multiplier;
+end
+
+local function addGroupDelimiters(numberStr, delimiter)
+	local formatted = numberStr
+	local delimiterSubStr = string.format("%%1%s%%2", delimiter)
+	while true do
+		local lFormatted, k = string.gsub(formatted, "^(-?%d+)(%d%d%d)", delimiterSubStr)
+		formatted = lFormatted
+		if k == 0 then
+			break
+		end
+	end
+	return formatted
+end
+
+local function findDenominationEntry(localeInfo, number, roundingBehaviourType)
+	local denominationEntry = localeInfo[1] -- Default to base denominations
+	local absOfNumber = math.abs(number)
+	for i = #localeInfo, 2, -1 do
+		local entry = localeInfo[i]
+		local baseValue
+		if roundingBehaviourType == RoundingBehaviourTypes.Truncate then
+			baseValue = entry[1]
+		else
+			baseValue = entry[1] - (localeInfo[i - 1][1]) / 2
+		end
+		if baseValue <= absOfNumber then
+			denominationEntry = entry
+			break
+		end
+	end
+	return denominationEntry
+end
+
+function NumberLocalizationUtils.localize(number, locale)
+	if number == 0 then
+		return "0"
+	end
+
+	local localeInfo = localeInfos[locale]
+	if not localeInfo then
+		localeInfo = localeInfos[DEFAULT_LOCALE]
+		warn(string.format("[NumberLocalizationUtils] - Locale not found: '%s', reverting to '%s' instead.",
+			tostring(locale), DEFAULT_LOCALE))
+	end
+
+    if localeInfo.groupDelimiter then
+        return addGroupDelimiters(number, localeInfo.groupDelimiter)
+    end
+
+    return number
+end
+
+function NumberLocalizationUtils.abbreviate(number, locale, roundingBehaviourType, numSignificantDigits)
+	if number == 0 then
+		return "0"
+	end
+
+	if roundingBehaviourType == nil then
+		roundingBehaviourType = RoundingBehaviourTypes.RoundToClosest
+	end
+
+	if numSignificantDigits == nil then
+		numSignificantDigits = 3
+	end
+
+	local localeInfo = localeInfos[locale]
+	if not localeInfo then
+		localeInfo = localeInfos[DEFAULT_LOCALE]
+		warn(string.format("[NumberLocalizationUtils] - Locale not found: '%s', reverting to '%s' instead.",
+			tostring(locale), DEFAULT_LOCALE))
+	end
+
+	-- select which denomination we are going to use
+	local denominationEntry = findDenominationEntry(localeInfo, number, roundingBehaviourType)
+	local baseValue = denominationEntry[1]
+	local symbol = denominationEntry[2]
+
+	-- Round to required significant digits
+	local significantQuotient = roundToSignificantDigits(number / baseValue, numSignificantDigits, roundingBehaviourType)
+
+	-- trim to 1 decimal point
+	local trimmedQuotient
+	if roundingBehaviourType == RoundingBehaviourTypes.Truncate then
+		trimmedQuotient = math.modf(significantQuotient * 10) / 10
+	else
+		trimmedQuotient = math.floor(significantQuotient * 10 + 0.5) / 10
+	end
+	local trimmedQuotientString = tostring(trimmedQuotient)
+
+	-- Split the string into integer and fraction parts
+	local decimalPointIndex = findDecimalPointIndex(trimmedQuotientString)
+	local integerPart = string.sub(trimmedQuotientString, 1, decimalPointIndex - 1)
+	local fractionPart = string.sub(trimmedQuotientString, decimalPointIndex + 1, #trimmedQuotientString)
+
+	-- Add group delimiters to integer part
+	if localeInfo.groupDelimiter then
+		integerPart = addGroupDelimiters(integerPart, localeInfo.groupDelimiter)
+	end
+
+	if #fractionPart > 0 then
+		return integerPart .. localeInfo.decimalSeparator .. fractionPart .. symbol
+	else
+		return integerPart .. symbol
+	end
+end
+
+return NumberLocalizationUtils

package/src/Client/NumberLocalizationUtils.spec.lua

@@ -0,0 +1,110 @@
+local require = require(script.Parent.loader).load(script)
+
+local NumberLocalizationUtils = require("NumberLocalizationUtils")
+local RoundingBehaviour = require("RoundingBehaviourTypes")
+
+return function()
+
+	local function checkLocale(locale, responseMapping)
+		for input, output in pairs(responseMapping) do
+			expect(NumberLocalizationUtils.localize(input, locale)).to.equal(output)
+		end
+	end
+
+	local function checkValid_en_zh(locale)
+		checkLocale(locale, {
+			[0] = "0",
+			[1] = "1",
+			[25] = "25",
+			[364] = "364",
+			[4120] = "4,120",
+			[57860] = "57,860",
+			[624390] = "624,390",
+			[7857000] = "7,857,000",
+			[-12345678] = "-12,345,678",
+			[23987.45678] = "23,987.45678",
+			[-12.3456] = "-12.3456",
+			[-23987.45678] = "-23,987.45678",
+		})
+	end
+
+	describe("NumberLocalizationUtils.localize", function()
+		-- it("should default to en-us when locale is not recognized", function()
+		-- 	local logs = Logging.capture(function()
+		-- 		checkValid_en_zh("bad_locale")
+		-- 	end)
+		-- 	expect(string.match(logs.warnings[1], "^Warning: Locale not found:") ~= nil).to.equal(true)
+		-- end)
+
+		-- it("should default to en-us when locale is nil", function()
+		-- 	local logs = Logging.capture(function()
+		-- 		checkValid_en_zh(nil)
+		-- 	end)
+		-- 	expect(string.match(logs.warnings[1], "^Warning: Locale not found:") ~= nil).to.equal(true)
+		-- end)
+
+		-- it("should default to en-us when locale is empty", function()
+		-- 	local logs = Logging.capture(function()
+		-- 		checkValid_en_zh("")
+		-- 	end)
+		-- 	expect(string.match(logs.warnings[1], "^Warning: Locale not found:") ~= nil).to.equal(true)
+		-- end)
+
+		it("should localize correctly. (en-us)", function()
+			checkValid_en_zh("en-us")
+		end)
+
+		it("should localize correctly. (en-gb)", function()
+			checkValid_en_zh("en-gb")
+        end)
+
+        it("should localize correctly. (zh-cn)", function()
+			checkValid_en_zh("zh-cn")
+		end)
+
+		it("should localize correctly. (zh-tw)", function()
+			checkValid_en_zh("zh-tw")
+        end)
+	end)
+
+	describe("NumberLocalizationUtils.abbreviate", function()
+		it("should round towards zero when using RoundingBehaviour.Truncate", function()
+			local roundToZeroMap = {
+				[0] = "0",
+				[1] = "1",
+				[25] = "25",
+				[364] = "364",
+				[4120] = "4.1K",
+				[57860] = "57.8K",
+				[624390] = "624K",
+				[999999] = "999K",
+				[7857000] = "7.8M",
+				[8e7] = "80M",
+				[9e8] = "900M",
+				[1e9] = "1B",
+				[1e12] = "1,000B",
+				[-0] = "0",
+				[-1] = "-1",
+				[-25] = "-25",
+				[-364] = "-364",
+				[-4120] = "-4.1K",
+				[-57860] = "-57.8K",
+				[-624390] = "-624K",
+				[-999999] = "-999K",
+				[-7857000] = "-7.8M",
+				[-8e7] = "-80M",
+				[-9e8] = "-900M",
+				[-1e9] = "-1B",
+				[-1e12] = "-1,000B",
+				[1.1] = "1.1",
+				[1499.99] = "1.4K",
+				[-1.1] = "-1.1",
+				[-1499.99] = "-1.4K",
+			}
+
+			for input, output in pairs(roundToZeroMap) do
+				expect(NumberLocalizationUtils.abbreviate(input, "en-us", RoundingBehaviour.Truncate)).to.equal(output)
+			end
+		end)
+	end)
+end

package/src/Client/RoundingBehaviourTypes.lua

@@ -0,0 +1,12 @@
+--[=[
+	@class RoundingBehaviourTypes
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local Table = require("Table")
+
+return Table.readonly({
+	RoundToClosest = "roundToClosest";
+	Truncate = "truncate";
+})

package/src/Shared/JsonToLocalizationTable.lua

@@ -15,11 +15,13 @@ local LOCALIZATION_TABLE_NAME = "GeneratedJSONTable"
 
 --[[
 	Recursively iterates through the object to construct strings and add it to the localization table
+
+	@param localizationTable LocalizationTable
 	@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)
+local function recurseAdd(localizationTable, localeId, baseKey, object, tableName)
 	if baseKey ~= "" then
 		baseKey = baseKey .. "."
 	end
@@ -27,10 +29,13 @@ local function recurseAdd(localizationTable, localeId, baseKey, object)
 	for index, value in pairs(object) do
 		local key = baseKey .. index
 		if type(value) == "table" then
-			recurseAdd(localizationTable, localeId, key, value)
+			recurseAdd(localizationTable, localeId, key, value, tableName)
 		elseif type(value) == "string" then
 			local source = ""
-			local context = ""
+
+			-- Guarantee the context is unique. This is important because Roblox will not
+			-- allow something with the same source without a differing context value.
+			local context = tableName .. "." .. key
 
 			if localeId == "en" then
 				source = value
@@ -45,6 +50,7 @@ end
 
 --[=[
 	Extracts the locale from the name
+
 	@param name string -- The name to parse
 	@return string -- The locale
 ]=]
@@ -56,6 +62,12 @@ function JsonToLocalizationTable.localeFromName(name)
 	end
 end
 
+--[=[
+	Gets or creates the global localization table. If the game isn't running (i.e. test mode), then
+	we'll just not parent it.
+
+	@return string -- The locale
+]=]
 function JsonToLocalizationTable.getOrCreateLocalizationTable()
 	local localizationTable = LocalizationService:FindFirstChild(LOCALIZATION_TABLE_NAME)
 
@@ -72,19 +84,23 @@ function JsonToLocalizationTable.getOrCreateLocalizationTable()
 end
 
 --[=[
-	Loads a folder into a localization table
+	Loads a folder into a localization table.
+
+	@param tableName string -- Used for source
 	@param folder Folder -- A Roblox folder with StringValues containing JSON, named with the localization in mind
 ]=]
-function JsonToLocalizationTable.loadFolder(folder)
+function JsonToLocalizationTable.loadFolder(tableName, folder)
+	assert(type(tableName) == "string", "Bad tableName")
+
 	local localizationTable = JsonToLocalizationTable.getOrCreateLocalizationTable()
 
 	for _, item in pairs(folder:GetDescendants()) do
 		if item:IsA("StringValue") then
 			local localeId = JsonToLocalizationTable.localeFromName(item.Name)
-			JsonToLocalizationTable.addJsonToTable(localizationTable, localeId, item.Value)
+			JsonToLocalizationTable.addJsonToTable(localizationTable, localeId, item.Value, tableName)
 		elseif item:IsA("ModuleScript") then
 			local localeId = JsonToLocalizationTable.localeFromName(item.Name)
-			recurseAdd(localizationTable, localeId, "", require(item))
+			recurseAdd(localizationTable, localeId, "", require(item), tableName)
 		end
 	end
 	return localizationTable
@@ -92,17 +108,21 @@ end
 
 --[=[
 	Extracts the locale from the folder, or a locale and table.
+
+	@param tableName string -- Used for source
 	@param first Instance | string
 	@param second table?
 	@return LocalizationTable
 ]=]
-function JsonToLocalizationTable.toLocalizationTable(first, second)
+function JsonToLocalizationTable.toLocalizationTable(tableName, first, second)
+	assert(type(tableName) == "string", "Bad tableName")
+
 	if typeof(first) == "Instance" then
-		local result = JsonToLocalizationTable.loadFolder(first)
+		local result = JsonToLocalizationTable.loadFolder(tableName, first)
 		-- result.Name = ("JSONTable_%s"):format(first.Name)
 		return result
 	elseif type(first) == "string" and type(second) == "table" then
-		local result = JsonToLocalizationTable.loadTable(first, second)
+		local result = JsonToLocalizationTable.loadTable(tableName, first, second)
 		return result
 	else
 		error("Bad args")
@@ -111,27 +131,35 @@ end
 
 --[=[
 	Extracts the locale from the name
+
+	@param tableName string -- Used for source
 	@param localeId string -- the defaultlocaleId
 	@param dataTable table -- Data table to load from
 	@return LocalizationTable
 ]=]
-function JsonToLocalizationTable.loadTable(localeId, dataTable)
+function JsonToLocalizationTable.loadTable(tableName, localeId, dataTable)
+	assert(type(tableName) == "string", "Bad tableName")
+
 	local localizationTable = JsonToLocalizationTable.getOrCreateLocalizationTable()
 
-	recurseAdd(localizationTable, localeId, "", dataTable)
+	recurseAdd(localizationTable, localeId, "", dataTable, tableName)
 
 	return localizationTable
 end
 
 --[=[
 	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
+	@param tableName string -- Used for source
 ]=]
-function JsonToLocalizationTable.addJsonToTable(localizationTable, localeId, json)
+function JsonToLocalizationTable.addJsonToTable(localizationTable, localeId, json, tableName)
+	assert(type(tableName) == "string", "Bad tableName")
+
 	local decodedTable = HttpService:JSONDecode(json)
-	recurseAdd(localizationTable, localeId, "", decodedTable)
+	recurseAdd(localizationTable, localeId, "", decodedTable, tableName)
 end
 
 return JsonToLocalizationTable