-- LOCALIZATION -- 
-- 
-- © Jun 2000, James Newton <james.newton@openspark.com>
--
----------------------------------------------------------------------
-- 020801 JN: the aChildStringList parameter made more flexible to
--            allow strings or linear lists as well as property lists
-- 040318 JN: the aChildStringList can now be a symbol, which will
--            itself be localized
----------------------------------------------------------------------
-- In order to provide localized versions of a given string, set the
-- global gUserLanguage to one of the values used in the handler
-- below.  Default strings will be returned in English if 
-- 
-- * gUserLanguage is <Void> -- which it will be be default 
-- 
-- * gUserLanguage is different from the strings used in the handler
--   below.  If you wish to add a new language, simply copy and paste
--   one of the case sections and provide your own localized strings. 
-- 
-- HANDLERS: 
-- * GetLocalizedString(aStringSymbol) 
--   Returns a string in the appropriate language. 
--   Syntax: 
--     localString = GetLocalizedString(aStringSymbol) 
--     localString = sendSprite(0, #GetLocalizedString, aStringSymbol) 
-- 
-- * SubstituteStrings(aParentString, aChildStringList) 
--   Returns a string where all the property names in aChildStringList
--   are replaced by the corresponding values.
--   Syntax: 
--     substitutedString = SubstituteStrings(aString, aPropertyList) 
-- 
-- * GetStringSymbolsList() 
--   Returns a list of all the symbols supported by this script. 
--   Syntax: 
--     stringSymbolsList = GetStringSymbolsList() 
--     stringSymbolsList = sendSprite(0, #GetStringSymbolsList) 
-- 
-- Use the sendSprite(0) syntax if you are not sure whether this
-- script is available.
----------------------------------------------------------------------



on GetLocalizedString(aStringSymbol, aChildStringList) ---------------
  -- INPUT: <aStringSymbol> should be a symbol
  --        <aChildStringList> may be:
  --          - <Void>
  --          - a property list with the format ["^x": <string>, ...]
  --          - a linear list with the format [<string>, <string>,...]
  --            which will be converted to
  --            ["^0": <string>, "^1": <string>]
  --          - any other datatype, which will be converted to
  --            ["^0": string(aChildStringList)]
  -- OUTPUT: returns the string associated with <aStringSymbol> in the
  --         appropriate language
  --------------------------------------------------------------------
  
  case ilk(aChildStringList) of
    #void, #propList: -- continue
      
    #list: -- Convert to a proplist using "^0", "^1", ... as props
      tTemp = aChildStringList
      aChildStringList = [:]
      tCount = tTemp.count
      repeat with i = 1 to tCount
        aChildStringList.addProp("^"&i - 1, tTemp[i])
      end repeat
      
    #symbol:
      aChildStringList = ["^0": GetLocalizedString(aChildStringList)]
      
    otherwise: aChildStringList = ["^0": string(aChildStringList)]
  end case
  
  if aStringSymbol = #GetLocalizedString then
    
    -- The sendSprite(0, ...) syntax has probably been used.  There
    -- is, however, a remote chance that #GetLocalizedString is being
    -- used as a string symbol
    
    tTemp = param(2)
    if symbolP(tTemp) then
      aStringSymbol = tTemp
    end if
  end if
  
  tUserLanguage = (the globals)[#gUserLanguage]
  
  if voidP(tUserLanguage) then
    -- Use the system language
    tUserLanguage = the environment[#osLanguage]
  end if
  
  tMessage = "" -- pre-emptive in case the string does not exist
  
  case tUserLanguage of
    "French":
      case aStringSymbol of
          -- Simple examples 
        #yes:      return "Oui"
        #no:       return "Non"
        #ok:       return "OK"
        #cancel:   return "Annuler"
        #dontAsk:  return "Ne plus demander"
        #dontShow: return "Ne plus afficher"
          
        otherwise:
          -- string symbol unknown
          return string(aStringSymbol)
      end case
      
      -- Add other language cases here
      
    otherwise
      case aStringSymbol of
        #yes:      return "Yes"
        #no:       return "No"
        #ok:       return "OK"
        #cancel:   return "Cancel"
        #dontAsk:  return "Don't ask again"
        #dontShow: return "Don't show again"
          
        otherwise:
          -- string symbol unknown
          return string(aStringSymbol)
      end case
  end case
  
  return SubstituteStrings(tMessage, aChildStringList)
end GetLocalizedString



on SubstituteStrings(aParentString, aChildStringList) ----------------
  -- INPUT: <aParentString> is a string possibly containing one or
  --         more ^x words, where x is an integer
  --        <aChildStringList> should be a property list with the
  --         format ["^x": "replacement string", ...]
  -- OUTPUT: Modifies and returns <aParentString> so that the strings
  --         which appear as properties in <aChildStringList> are
  --         replaced by the values associated with those properties.
  --------------------------------------------------------------------
  
  if ilk(aChildStringList) <> #propList then
    return aParentString
  end if
  
  i = aChildStringList.count()
  
  repeat while i
    tString = ""
    tDummy  = aChildStringList.getPropAt(i)
    if stringP(tDummy) then
      tLength = tDummy.char.count - 1
      
      tChild  = aChildStringList[i]
      if symbolP(tChild) then
        tChild = GetLocalizedString(tChild)
      end if
      
      repeat while TRUE
        tOffset = offset(tDummy, aParentString)
        if not tOffset then
          aParentString = tString&aParentString
          exit repeat
        else
          if tOffset <> 1 then
            tString = tString&aParentString.char[1..tOffset - 1]
          end if
          tString = tString&tChild
          delete aParentString.char[1..tOffset + tLength]
        end if
      end repeat
    end if
    
    i = i - 1
  end repeat
  
  return aParentString
end SubstituteStrings



on GetStringSymbolsList() --------------------------------------------
  -- This handler will only work if the current script is in an
  -- unprotected cast.  This should always be true while authoring.
  -- It also requires that the current script be the lowest-numbered
  -- member named "Localization"
  --
  -- OUTPUT: a list of the string symbols supported by this script.
  --------------------------------------------------------------------
  
  tStringSymbols = []
  
  tLocalizationMember = member("Localization").number
  if tLocalizationMember < 1 then
    -- This script has been renamed
    exit
  end if
  
  tLocalizationScript = member(tLocalizationMember).scriptText
  
  tOffset = offset("case aStringSymbol of", tLocalizationScript)
  if not tOffset then
    -- This script is not the lowest-numbered member named
    -- "Localization"
    exit
  end if
  
  tLine = tLocalizationScript.char[1..tOffset].line.count
  delete tLocalizationScript.line[1..tLine]
  tCount = tLocalizationScript.line.count
  
  repeat with tLine = 1 to tCount
    tSymbol = tLocalizationScript.line[1].word[1]
    delete tLocalizationScript.line[1]
    -- <tSymbol> is likely to be something like "#stringSymbol:"
    
    if tSymbol = "otherwise:" then
      -- We have reached the end of the registered symbols
      exit repeat
      
    else if tSymbol.char[1] = "#" then
      -- We've found the next registered symbol
      delete tSymbol.char[1] -- "#"
      delete the last char of tSymbol -- ":"
      tStringSymbols.append(symbol(tSymbol))
    end if 
  end repeat
  
  return tStringSymbols
end GetStringSymbolsList




-- DESCRIPTION --

on getBehaviorDescription (me) ---------------------------------------
  -- Uses the Automatic Script Description movie script
  --
  -- The handler name is followed by a space: this handler will not 
  -- appear in the Behavior Inspector
  --------------------------------------------------------------------
  
  scriptName = sendSprite(0, #getScriptName, me)
  if stringP(scriptName) then
    code = member(scriptName).scriptText
    return \
getInitialComments(code)&RETURN&RETURN&\
getHandlerData(code)
  end if
end getBehaviorDescription