W3C home > Mailing lists > Public > public-i18n-its@w3.org > July to September 2005

Tim's comments on requirements doc.

From: Tim Foster <Tim.Foster@Sun.COM>
Date: Wed, 20 Jul 2005 17:27:32 +0100
To: public-i18n-its@w3.org
Message-id: <1121876852.16436.230.camel@cuprum>

Hey Folks,

Here's my (very late) comments on the current editor's copy of
http://www.w3.org/International/its/requirements/
(sorry, this is a long mail!)

They're mostly typos and grammar, I'll quote the original text of the
document with '>' characters so you can easily find text in the
original. I'll also mark the section I'm talking about.

I'm not 100% confident of all of these suggestions, so perhaps someone
could review these, in case I'm incorrect in suggesting these changes ?

(it might be useful if each section refers to the wiki page it was
generated from, that would make adding comments/suggested changes to the
draft a lot easier...)

Here goes :

Section 1.1

> The increasing usage of XML as a medium for documentation-related
> content (e.g. DocBook as a format for related to user manuals) and 

"e.g. DocBook, being a format for writing structured documentation, well
suited to computer hardware and software manuals."

[ I used the answer to the "What is Docbook?" FAQ question from
http://www.dpawson.co.uk/docbook/reference.html#d4e16 as a basis for
this re-wording ]

---

Section 1.3

> Such usage would be similar to the <style> element in an HTML
> document.

Not sure, do we phrase it as "a HTML document" or "an HTML document" ?
(guess it depends on whether you pronounce the 'H' in HTML as "haitch"
or "aytch" : W3C folks any ideas ? )

> Such approaches are not meant to describe the configuration settings
> (i.e. localization properties) of localization tools for XML content.

Can we rephrase this to :

"Such approaches are not meant to describe the configuration settings of
localisation tools for XML content."

- we haven't yet introduced the term "localisation properties", so
leaving it more generic would seem to make sense for now (this is
related to my thoughts about the RecTranslatability section that I'll
suggest in the wiki later)

---

Section 1.4 Key Definitions

Richard was going to work on the wording of this a bit, to perhaps
suggest that these are possible definitions of l10n and i18n, but that
other definitions are used elsewhere.

---

2.1.1 Description

> terms that should not be translated or translated using a pre-existing
> terminology list

Perhaps rephrase to : 

"terms that either should not be translated or should be translated
using a pre-existing terminology list"


> The use of a standardized set of tags allows the authoring systems to
> provide a common solution for these special markers across all XML
> documents.

Perhaps rephrase to (s/the authoring systems/authoring systems/)

"The use of a standardized set of tags allows authoring systems to
provide a common solution for these special markers across all XML
documents."

---

Section 2.1.2 Stakeholders

Perhaps replace each list item starting with "The ..." to just "...",
eg.

"The technical writers developing authoring content" 
would change to
"Technical writers developing authoring content"


---

Section 2.2.1 Description

> This list is used to provided a consistent terminology across the
> different parts of the documentation.

typo "provided" -> "provide"


> The same markup can be used further down the project, during
> translation, to help the translators match up the source terms with
> their agreed-upon translations.

Not completely clear what "the project" is. Perhaps rephrase to :

"The same markup can be used at later steps in the translation process,
to help translators match up source terms with their agreed-upon
translations"

likewise

> The use of a common set of markers allows afor better re-usability of
> the information across the different steps of the process and across
> the various tools used to facilitate that process.

Again, perhaps say which process we're talking about : the "translation
process" or "localisation process" maybe ?

---

Section 2.2.2 Stakeholders

(similar comments as for section 2.1.2)

---

Section 2.3.1

(A few minor wording changes here)

> For example: UI resources and message files, comments in the source
> code to generate documentation, or even temporary XML storage
> generated from proprietary formats for the time of the localization.

Could we make the above a sentence ? Something like, 

"Examples of this, would be UI resources and message files, comments in
the source code to generate documentation, or even temporary XML storage
generated from proprietary formats for the time of the localization"

> A software developer often needs to provide localization-related
> information with the resources that will be translated.

"A software developer often needs to provide localization-related
information along with the resources that will be translated."

> For instance, he or she needs to indicate that a string has a maximum
> length because the program reads it using a fixed-length buffer.

For instance, he or she may need to indicate that a string has a maximum
length because the software processes it using a fixed-length buffer.

---

2.3.2 Stakeholders

(same comments as before)

---

3.2.1 Challenges
(wow, I even need to correct myself from time to time ;-)

> in source files that translation tools can also be used to determine
> which translation process

should be :

"in source files that translation tools can use to determine which
translation process"

---

3.4.2 Notes

> The xml:id attribute [XML ID] may be a mean to carry the unique
> identifier.

typo --

"The xml:id attribute [XML ID] may be a means to carry the unique
identifier.

---

3.6.1 Challenges

> In order to simplify parsing process by documentation and
> localization tools

"In order to simplify the parsing process of documentation and 
localization tools" (perhaps ?)

---

3.7.1 .


> Meanwhile, identified terms could be used for indexing that may
> require some language specific information .For example, Japanese
> words are sorted not by script characters, but by phonetic characters.
> Therefore when a Japanese index item should be accompanied with a
> phonetic string, called Yomigana.

change to :

"Meanwhile, identified terms could be used for indexing that may require
some language specific information. For example, Japanese words are
sorted not by script characters, but by phonetic characters. Therefore
when a Japanese index item is created, it should be accompanied by a
phonetic string, called Yomigana."

- is that correct ?

---

3.8.1 Challenges :

> Some reasons why this type of markup may require special attention:

Maybe change to :

"Here are some reasons why this type of markup may require special
attention :" 

(again, not sure on this, it's a style thing, I guess)


---

3.9.1

> Examples of issues are as followings:

"Here are some examples of these type of issues:"

?

---

3.12.1

> The mechanism should also allow to specify exceptions within
> exceptions

not sure that sounds right, but maybe I'm wrong. How about :

"The mechanism should also allow one to specify exceptions within
exceptions"

or maybe

"The mechanism should also allow for specification of  exceptions within
exceptions"

Similar (possible) problems with the next sentence :

> ... it should allow to specify that <text> is to be translated, but
> also that some occurrences of the <text> element (e.g. with an
> attribute translate="no") are not to be translated.

either "... it should allow one to specify"

or

"... it should allow for the specification of the fact that the <text>
element is to be translated..."


"The mechanism should be able to map existing elements that already
carry implicitly or explicitly the translatability information."

That sentence is fine, but it could be good to add a sentence

"Here are some examples of this :"

(a bullet list of examples follows that sentence)

> The mechanism should provide a way to delimit a portion of the content
> if such mechanism does not exists in the original vocabulary (so parts
> of a content could be set to be translated or not).

Perhaps replace with :

"The mechanism should provide a way to delimit a portion of the content
of the content if such a mechanism does not exist in the original
vocabulary (so parts of the content could be marked as translatable or
not)"

---

3.14.1

> Any solution for one of the ITS requirements must take in account
> these potential drawbacks and offer implementations that has a limited
> impact in the original document and on the content models in the
> original schema.

perhaps change to :

"Solutions for any of the ITS requirements must take into account these
potential drawbacks and offer implementations that have limited impact
on the original document and on the content models in the original
schema."




Okay, that's all I've got so far : hope these are useful.

Yves, if you like, I can spend some time going through the Wiki, 
applying these changes myself to the items in there. That was something
we discussed in todays call, I don't mind doing that, but it'd be nice
to only have to fix these once ;-)

	cheers,
			tim

-- 
Tim Foster - Tools Engineer, Software Globalisation
Project Lead, Open Language Tools https://open-language-tools.dev.java.net/
http://blogs.sun.com/timf  http://www.netsoc.ucd.ie/~timf
Received on Wednesday, 20 July 2005 16:32:00 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 8 January 2008 14:12:45 GMT