Hi If there is a demand for NLS (and I see there is) let’s add it to the coding guide. As mentioned the performance overhead is negligible, let’s just make sure we keep the development and deployment overhead negligible as well.
--Eli -----Original Message----- From: Bryant Luk [mailto:[email protected]] Sent: Thursday, June 11, 2009 6:26 PM To: [email protected] Subject: Re: Wink Project Guidelines Looking at other open source projects, there have been a number of volunteers willing to translate documentation to other languages. For instance, the Japanese Apache Geronimo user group did a translation of the site guide at one point (http://cwiki.apache.org/confluence/display/GMOxDOC20ja/Documentation). Some Eclipse features and plugins do translations of their logs to help their users and to help those that are trying to extend from them. If users are willing to do that, I think we should allow it because it grows the community using the runtime (runtime project developers, application developers using the runtime, and end users). While I expect the primary communication language to always be English, I don't think we should put any barriers up for adoption. With all that said, for the coding portion, I do consider some of our users to be application developers. In my view, warning, information, and error log messages are intended for consumption by them. If someone is willing to provide a translation to help their native language users, then let them do that work, but I think we should leave the option available. As Mike said, the runtime engine debug log messages are really intended for runtime project developers since even if it was translated, I don't think non-project developers are expected to grasp what is being logged in debug mode. >From a technical point of view, I don't think there's a sizable performance penalty by doing the message lookup. I think you could also just not distribute the translation files and default to one. Given that there are virtually no string messages that end up back to the "end client user", I don't think there is a significant amount of work here either. On Thu, Jun 11, 2009 at 9:37 AM, Baram, Eliezer<[email protected]> wrote: > The written output that we provide to the application developer is a lot > wider then the log messages. It include the Java API of the framework, > javadoc, developer guide, readme files, the content of WINK site and even the > JAX-RS spec. > > Since an application developer need to read at least part of these written > outputs in order to be able to work with the framework, I think that a fair > assumption would be that he has the basic English capabilities to understand > log messages. > > That's why I do not feel convenience to refer to application developer and > end users in the same manner regarding message translating. > > > > > > -----Original Message----- > From: Jesse A Ramos [mailto:[email protected]] > Sent: Thursday, June 11, 2009 4:55 PM > To: [email protected] > Subject: RE: Wink Project Guidelines > > I think Bryant and Mike are thinking of "users" to mean all users of the > runtime which includes both application developers and users of those > applications. In this sense, "developer" would refer more to the runtime > developers, and not application developers. > > Although we likely won't be returning messages to users of applications > (it was pointed out that WebApplicationException does not accept > messages), I think it would be helpful to application developers who may > wish to do their own debugging, as Mike mentioned, to have messages > exposed to them be translated. > > - Jesse > > > > > > "Baram, Eliezer" <[email protected]> > 06/11/2009 08:24 AM > Please respond to > [email protected] > > > To > "[email protected]" <[email protected]> > cc > > Subject > RE: Wink Project Guidelines > > > > > > > My rule of thumb regarding message translating is: messages that are aimed > for users should be translated and message that are aimed for developers > should not be translated. > > Does this rule of thumb seems valid to you? > > I do not think that the REST framework generate messages that are aimed to > the end users, even the warning that the JAX-RS spec suggests are aimed to > the application developer that uses the framework and not to the user of > the application. > > > > -----Original Message----- > From: Bryant Luk [mailto:[email protected]] > Sent: Thursday, June 11, 2009 3:59 PM > To: [email protected] > Subject: Re: Wink Project Guidelines > > I was thinking more about the log.warn() messages in this respect too. > There are a few places (mainly in the application configuration) > where the JAX-RS spec suggests issuing warnings. It would be nice > that if a translation were available, that it be used in those default > customer facing messages. I'm fairly certain we would have some debug > information in those areas which would not be translated. > > On Thu, Jun 11, 2009 at 7:15 AM, Michael Rheinheimer<[email protected]> > wrote: >> Hi Michael, >> >> From working on the IBM code base, I think Bryant means that strings > passed >> through log.error would be externalized (for NLS), but messages passed >> through log.debug would not be. I guess it depends on the logging > mechanism >> whether log.error is a "message that can be returned to the user" or > not. I >> would expect log.error to be configured to go to an error log, or even >> System.err if that's appropriate for the given runtime environment. I > think >> the intent for log.error in the IBM runtime was to report user errors, > not >> JAX-RS engine data dumps -- that would be reserved for log.debug. The >> log.error messages are intended to help the customer solve an issue >> him/herself, such as if an important annotation has been forgotten (see >> org.apache.cxf.jaxrs.utils.JAXRSUtils.findTargetMethod where the > log.error >> reports that a resource has no GET, POST, PUT, or DELETE annotations, > for >> example). So with that in mind, I would want log.error messages to be >> readable by the customer in their language of choice. >> >> However, you make a good point that this means the log.error messages > are >> perhaps in a language unknown by the support team, but the log.debug >> messages would be. So, what's the solution to this? Do we: >> >> 1) do not externalize anything that goes through log.*, thus > externalizing >> only the messages in a thrown exception or message response body? or >> 2) use log.debug and log.error side-by-side every place a log.error > message >> might appear so we can report in both a customer's language and English? > (I >> don't like this option) >> 3) others? >> >> Ideally, I think log.error would be used to report NLS strings so a > customer >> can quickly resolve the error him/herself without requiring a call to >> support. >> >> Your thoughts? >> >> >> Mike Rheinheimer >> (512) 838-0086 t/l 678-0086 >> WebSphere WebService Core Engine Team >> >> >> "Elman, Michael" ---06/11/2009 02:58:57 AM---Well, I'm not quite sure > that >> logging messages should be externalized. I mean here the messages that >> >> >> From: >> "Elman, Michael" <[email protected]> >> To: >> "[email protected]" <[email protected]> >> Date: >> 06/11/2009 02:58 AM >> Subject: >> RE: Wink Project Guidelines >> ________________________________ >> >> >> Well, I'm not quite sure that logging messages should be externalized. I >> mean here the messages that are only written to log files. It may happen >> that a problem will occur on the customer site and we'll ask for the > logs. >> I'm quite unsure that I want to read messages in a language I don't > know. >> >> I think that only messages that can be returned to the user must be >> externalized. In case of Wink, these can be messages thrown in > exceptions or >> put in the response body. >> >> Btw, there is almost no way to throw exceptions with a message that can > be >> returned to the user from the JAX-RS runtime. WebApplicationException > that >> should be thrown in most cases, has no constructors that accept > messages. >> And I don't think that throwing a RuntimeException with a message > embedded >> in the WebApplicationException is a good solution: the stacktrace looks >> weird; and actually the message will not be returned to the client, > since >> the default handling of WebApplicationException ignores the message. >> >> Michael Elman >> >> >> -----Original Message----- >> From: Bryant Luk [mailto:[email protected]] >> Sent: Wednesday, June 10, 2009 5:21 PM >> To: [email protected] >> Subject: Re: Wink Project Guidelines >> >> One quick note, I added an explicit part for logging messages. >> Basically I think we should externalize any logging message strings >> into a message.properties file that are not debug messages (for NLS >> and the like). >> >> On Tue, Jun 9, 2009 at 9:26 AM, Bryant Luk<[email protected]> wrote: >>> I like the coding guidelines. I think using Maven would be good. The >>> only issue I think we need to address is making sure that we allow the >>> integration tests to run on various platforms.(jetty, tomcat, >>> geronimo, etc.), maybe via the Maven profiles functionality. >>> >>> On Mon, Jun 8, 2009 at 8:50 AM, Elman, Michael<[email protected]> wrote: >>>> I've created "Coding Guidelines" under the "Project Guidelines". >>>> Feel free to modify/add/discuss. >>>> >>>> Michael Elman >>>> >>>> >>>> -----Original Message----- >>>> From: Bryant Luk [mailto:[email protected]] >>>> Sent: Friday, June 05, 2009 6:10 AM >>>> To: [email protected] >>>> Subject: Re: Wink Project Guidelines >>>> >>>> >>>> I've updated the Wink Wiki with some of the project guidelines at: >>>> >>>> http://cwiki.apache.org/confluence/display/WINK/Project+Guidelines >>>> >>>> I copied what I thought was relevant for now. Feel free to >>>> modify/add/discuss. >>>> >>>> Thanks, >>>> >>>> Bryant Luk >>>> [email protected] >>>> >>>> >>>> Davanum Srinivas <[email protected]> wrote on 06/04/2009 08:25:09 PM: >>>> >>>>> [image removed] >>>>> >>>>> Re: Wink Project Guidelines >>>>> >>>>> Davanum Srinivas >>>>> >>>>> to: >>>>> >>>>> wink-dev >>>>> >>>>> 06/04/2009 08:26 PM >>>>> >>>>> Please respond to wink-dev >>>>> >>>>> Eli, Bryant, >>>>> >>>>> Feel free to use the wiki: >>>>> http://cwiki.apache.org/confluence/display/WINK/Index >>>>> >>>>> thanks, >>>>> dims >>>>> >>>>> On Thu, Jun 4, 2009 at 8:39 AM, Baram, Eliezer<[email protected]> wrote: >>>>> > Hi >>>>> > I think it can be a starting point, there are some modifications I >>>>> believe we should add, but in general it look good. >>>>> > let's copy it as a draft and then do the modifications and >>>>> discussions upon it. >>>>> > Regards, >>>>> > Eli >>>>> > >>>>> > >>>>> > >>>>> > >>>>> > -----Original Message----- >>>>> > From: Bryant Luk [mailto:[email protected]] >>>>> > Sent: Wednesday, June 03, 2009 11:39 PM >>>>> > To: [email protected] >>>>> > Subject: Wink Project Guidelines >>>>> > >>>>> > >>>>> > Hi all, >>>>> > >>>>> > For project guidelines, Jakarta seems to have a well written set >>>> (thanks >>>>> > Carlton): >>>>> > >>>>> > http://jakarta.apache.org/site/guidelines.html >>>>> > >>>>> > Any thoughts if we should just copy these guidelines for Wink? > Some >>>>> > of >>>>> > these aren't applicable but these seem fairly standard in how other >>>> Apache >>>>> > projects are run. >>>>> > >>>>> > I imagine that more coding guidelines would need to be done later >>>>> > (like >>>>> > maybe formatting, logging, NLS, etc.) >>>>> > >>>>> > Thanks, >>>>> > >>>>> > Bryant Luk >>>>> > [email protected] >>>>> > >>>>> >>>>> >>>>> >>>>> -- >>>>> Davanum Srinivas :: http://davanum.wordpress.com >>>> >>> >>> >>> >>> -- >>> >>> - Bryant Luk >>> >> >> >> >> -- >> >> - Bryant Luk >> >> >> > > > > -- > > - Bryant Luk > > -- - Bryant Luk
